Charts - Gauge

#Usage

import { ChartAnnotation, ChartCanvas, ChartCaption, ChartGauge, ChartHover, ChartItem, ChartLegend, ChartReferenceBand, ChartStacked, ChartSvg, ChartTitle, ChartTooltip, ChartXAxis } from '@primeui/vue-chart';

<ChartSvg>
    <ChartGauge :data="data" value-x-field="value" />
    <ChartXAxis />
</ChartSvg>

A gauge places a value on a numeric angular axis. Unlike a pie, the angle encodes the value against a domain rather than a share of a total, so a single reading is positioned rather than divided. Add ChartXAxis to draw the tick ring; without it the gauge is a bare arc.

min and max declare that domain, and each defaults to 0 and 100 on its own. A declared ChartXAxis outranks the series, so declare the domain in one place or the other: declaring it in both logs a development warning and the axis wins. The scale is a fixed default rather than one inferred from the readings, so it does not move underneath a value that changes. Readings clamp to the arc, so declare the bounds whenever the real full scale is not a percentage. A reading outside an undeclared scale logs a development warning rather than pinning the pointer without explanation.

Each reading is drawn as a filled bar with a needle over it. Several readings share one band, so the bars overlap: the largest is painted underneath, leaving every smaller reading visible on top of it, and each takes its own palette slot. Set bar to false for a pointer-only gauge, which also drops the unfilled track, since the track belongs to the filled style.

#Basic

Set valueXField to map the measured value and give the domain with min and max. A single reading fills from min to the value and carries a needle. Add ChartXAxis to label the scale; the tick count is chosen for the length of the arc, and tickInterval or tickCount overrides it.

#Bar

Set needle to false to leave the fill alone. bar is on by default, so the arc runs from the domain minimum to the value and the track behind it shows the remainder. This is the radial progress style common on dashboards.

#Needle

Set bar to false for the opposite reading: a pointer against a labelled scale with no fill and no track, which is how a dial instrument reads. The needle spans the full radius when the band is empty.

#Angles

Set startAngle and endAngle in degrees to shape the arc. 0 points right and angles run clockwise, so the 180 to 360 below is a top half-circle. The gauge is sized to fit the arc rather than a whole circle, so a half-circle keeps its width in a container only half as tall and leaves no blank half below it. Any finite number is accepted, negatives and values past 360 included, so a top half-circle reads as either 180 to 360 or -180 to 0; a sweep wider than a full turn is clamped to 360 so no part of the arc is drawn over another. The default 135 to 405 sweeps 270 degrees with the opening at the bottom, and a 360 degree sweep closes the ring. On a full circle the domain ends meet, so the maximum label would land on the minimum; the last one is dropped unless showLastLabel asks for it.

#Radius

Set innerRadius and outerRadius as ratios of the chart radius to control the band. The two together set its thickness, so a high innerRadius close to outerRadius gives the thin ring below, and lowering outerRadius pulls the whole gauge inward to leave room around it.

The pair is the gauge's frame: the scale the axis line, ticks, tick labels and reference bands are laid out on, and the ring the track fills. barInnerRadius and barOuterRadius inset the bar inside that frame and default to it, which is how a wide track sits behind a narrower reading without moving anything else. barBorderRadius does the same for the corners, leaving borderRadius to round the track.

#Multi Needle

Pass several rows to render one bar and one needle per row on the same scale. Use it to compare a current reading against a target or a previous period. This demo sets bar to false so the needles are the only pointers. needleColor accepts a callback or an array to tell them apart, and returning undefined leaves a needle at the default colour.

#Concentric Bars

Give each ChartGauge its own innerRadius and outerRadius to stack independent readings as concentric rings. Sharing an axis shares the domain and the arc, never the radii, so each ring keeps its own band, its own remainder and its own needle while the axis draws one tick ring at the outer edge.

#Segments

Set segments to a list of scale values to cut the track and the bar into pieces at those readings, and spacing to set the pixel gap between them. The gap is taken from the shared edges only, so the run still starts and ends exactly on the domain. A segmented bar fills as one reading rather than as four: the pieces run in order and the leading edge keeps pace with the needle.

#Colors

Pass a function to color to derive the fill from the reading, which is how threshold colouring is expressed. trackColor sets the unfilled remainder, and needleColor can take the same function so the pointer matches the band it sits in.

#Gradient Color

Pass a gradient object to color to fill the bar with a controlled ramp. The stops are declared in the gauge's own coordinate space, so the ramp follows the band rather than the chart box.

#Border

Set borderStrokeWidth and borderColor to stroke the filled bar. Use borderRadius for rounded arc caps and borderDash for a dashed stroke.

#Center Content

renderContent draws inside the hole and runs once per animation frame. It receives value for the settled reading and animatedValue for the in-flight one, so a count-up readout stays in step with the arc. The reading comes from the needle, or from the leading edge of the bar when there is no needle. Return a { text, style } descriptor for a plain reading, or a VNode for richer layouts in SVG mode.

#Custom Needle

renderNeedle replaces the default pointer. It returns an SVG path in absolute chart coordinates and receives the centre, the resolved angle, the length and the width, which is the same contract as the bar renderShape seam. In canvas mode the context is supplied for imperative drawing. The needle stops short of whatever occupies the band: the bar and its track, value bands, and an inward-growing tick ring all reserve their space first. With none of those present it spans the radius instead.

#Overshoot

Set overshoot to the number of degrees a needle may travel past either arc end, which keeps an out-of-range reading visibly out of range instead of pinned at the last tick. The reading below is 118 against a domain that stops at 100.

#Wrap

wrap carries values past max around to min instead of stopping at the arc end, which is how a clock hand or a compass behaves. It defaults on for a full-circle sweep. Readings inside the domain never wrap. The compass below is given a heading of 430 on a 0 to 360 scale, so the needle comes round to 70.

#Dual Scale

Declare several ChartXAxis entries to draw more than one tick ring on the same arc. Bind a gauge to one of them with xAxisId; the remaining axes render their own ring with their own domain, which is how a single reading is labelled in two units. Give the second ring its own offset and labelDistance so it clears the first: tickPosition moves only the marks, so two rings left at the default would put both sets of labels at the same radius.

#Stacked

Wrap several gauges in ChartStacked to accumulate them angularly along one scale, with each segment starting where the previous ended. The first member sets the shared domain and the shared band, so the ring stays one thickness. Percent mode does not apply, because a gauge already has a declared maximum.

#Declarative

Use ChartItem children instead of a data array to define readings inline. Each item becomes one needle, where valueX carries the value and category names it. The two modes are mutually exclusive.

#Title & Caption

Add ChartTitle and ChartCaption to label the chart. Both reserve layout space above the gauge, so the arc shrinks to fit rather than overlapping the text.

For full configuration see Title & Caption.

#Hover

Add ChartHover to enable hover feedback on the bar and the needle. brightness lightens the resolved fill, and hoverColor replaces it outright when a specific highlight is wanted.

For full configuration see Hover.

#Tooltip

Add ChartTooltip to show the reading under the pointer. Needles hit-test along the shaft and bar pieces across the arc, so both are reachable. categoryField supplies the label for each reading.

For full configuration see Tooltip.

#Legend

Add ChartLegend to toggle whole gauges. Legend entries are per dataset rather than per reading, so the legend is most useful with concentric or stacked gauges where each ring is a named series.

For full configuration see Legend.

#Axes

ChartXAxis drives the tick ring, and its min and max take precedence over the series domain. Set tickInterval or tickCount to control the majors, minorGridCount to subdivide them, and minorTicks to turn the smaller marks off. tickFormat formats the labels, tickStyle sets their font, colour, length, thickness and padding, offset moves the whole ring, and labelDistance places the labels at a signed distance from the axis line, independently of the marks.

#Custom Ticks

minorTickLength, minorTickColor and minorTickStrokeWidth style the minor marks apart from the majors, each falling back to its major counterpart. tickRotation turns the labels. For anything further, renderTick replaces a tick mark and render replaces a tick label: both receive the tick value, its formatted label, its index and its position, and the default is not drawn for whatever they replace. In SVG mode they return a node, in canvas mode they receive a context already translated to the tick and draw at the origin. A tick mark is placed in the tick's own frame with +y running outward along the radius, the direction the built-in tick line grows in, so a shape drawn at the origin radiates with the arc. Tick labels stay upright. Minor ticks are on by default, so a seam reads major to tell a major mark from a minor one the way the built-in mark does.

label titles the scale, placed outside the tick labels by titleGap at the sweep's mid-angle, which is where a cartesian axis title sits read onto an arc. Each ring carries its own, so two scales on one gauge can name their own units, and the arc shrinks to reserve the room.

#Data Labels

Add ChartDataLabels to print each reading on the bar that carries it. One label is drawn per reading rather than per painted piece, so a bar split by segments keeps a single label while stacked members each take their own. A gauge drawn without a bar has no arc for a label to sit on, so those fall below the pivot and stack when there are several. distance moves a label along the radius, and display="percentage" reads a value as its position in the domain rather than as a share of a total, which is the reading a gauge has and a pie does not.

For full configuration see Data Labels.

#Annotation

Add ChartAnnotation to draw targets, thresholds, and supporting text over the gauge. The needle is built in, so annotations are for the marks around it rather than the pointer itself.

For full configuration see Annotation.

#Reference Lines & Bands

Add ChartReferenceBand with numeric x1 and x2 to shade a value range on the gauge scale. A band sits over the track and under the bar by default; placement="afterData" moves it over the bar, so a translucent fill tints the reading with the zone it has reached. Bands clip to the domain, so one that runs past max stops at the arc end. Set label to name the range inside the arc, with labelColor, labelFontSize and labelFontWeight for a fill the tick-label colour cannot be read against.

Add ChartReferenceLine with a numeric x to mark a single value. It draws as a spoke across the ring at that value's angle, the arc reading of a vertical line on a cartesian chart, and takes stroke, lineStrokeWidth and lineDash. Lines default to placement="afterData", over the bar and the needle, because a threshold hidden behind the reading cannot be seen. label names the line, and labelPosition moves it along the spoke rather than around the arc: start at the inner edge, center mid-ring, end past the outer edge. labelBackground draws a rounded pill behind the text.

Both are drawn at full extent from the first frame rather than sweeping in with the bar, which is how cartesian and radial charts draw their reference chrome.

#Animation

Pass the chart-root animation prop (ChartSvg / ChartCanvas) to control entrance and update transitions. The gauge animates the value itself and derives every angle from it each frame, so the needle, the bar, and the centre reading can never disagree mid-transition. Needles rise from the domain minimum on entrance and bars grow from their start value.

For full configuration see Animation.

#Export

Add ChartExportMenu to let users download the chart as PNG, SVG, or PDF.

See Export for format options and programmatic export.

#Responsive

See Responsive for container sizing, aspect ratio, and breakpoint configuration.

#Accessibility

Each reading carries an accessible description, on its needle and on its bar, so a gauge with needle off still announces its value. A run split by segments is announced once rather than once per piece.

See Accessibility for ARIA labels, keyboard navigation, and screen reader support.

#API

#ChartGauge

Visual styling props with type accessor → R accept a static value, a per-reading array, a field name (keyof T), or a callback (ctx: ItemContext<T>) => R | undefined. Color-family arrays cycle modulo length; other accessor arrays clip and fall back to the series default. Angles are degrees, where 0 points right and values run clockwise. Radius props are ratios of the chart radius.

#GaugeRenderContext

Passed to renderContent once per animation frame.

#ChartItem

Use ChartItem as children of ChartGauge instead of a data array for inline readings.

#Related Docs

• Gauge Playground
• Reference Lines & Bands
• Data Labels
• Axes
• Tooltip
• Animation