---
id: "packages/active-charts/all-exports/gauge-chart"
title: "GaugeChart"
description: "GaugeChart, GaugeChartProps: generated from the source of active-charts."
url: "/packages/active-charts/all-exports/gauge-chart"
locale: "en"
revision: "g0mvjxwj5c-88bdbe1c:gauge-chart"
---

# GaugeChart

Exported by `@workspace/active-charts`. Generated from the package source; part of [the index of every export](/packages/active-charts/all-exports).

## `GaugeChart`

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `height` | `number` | yes | Container height in pixels. Width is always responsive. |
| `value` | `number` | yes | The current value. |
| `accessibility` | `StandaloneAccessibilityOptions` | no | Accessible name, description, data table and keyboard navigation. No `announcements`: it switches `<Chart>`'s interaction announcements, which this family does not make. |
| `animation` | `ScalarAnimationOption<"replay">` | no | How the gauge moves: its entrance and, as the one scalar that replays, the replay's timing (`replay.duration`, ADR-100). |
| `className` | `string` | no | Optional className applied to the outer container. |
| `contextMenu` | `FeatureOption<ChartContextMenuOptions<unknown, "export" \| "replay">>` | no | The chart's menu: the host's items, Replay animation while `replay` is on (T7; `features.replay: false` leaves it out), then Export. |
| `dataLabels` | `Pick<DataLabelOptions, "background" \| "format" \| "formatter">` | no | The notation of the value readout: `formatter` or the `format` shorthand, and an optional `background` behind it. The readout itself is essential and always drawn (FV4, ADR-072); its size and colour are the family's. |
| `dir` | `"ltr" \| "rtl"` | no | The chart's UI direction: the reading direction of its HTML text and chrome (tooltip, legend, menus, the accessible table), and the direction the context menu carries under `<body>`.  Left out, the chart inherits the direction of the page around it (the nearest `dir` attribute, else the computed CSS direction) and follows a later change of that attribute. It is never inferred from `locale`, and it never reverses an axis or reorders data: `reversed` stays an explicit axis choice. Under `rtl` the chrome mirrors (legend flow, tooltip side, context menu and submenus, report text in exports), a title-like label starts at the inline start, and a label placed by geometry (an axis tick, a slice or bar label) keeps its physical side; plot arrow keys stay spatial while legend and menu arrows follow the reading direction. |
| `endAngle` | `number` | no | Where the dial ends, the angle of `max`, on the same clock: more than 0° and less than 360° past `startAngle` (a dial is never a full circle). Default: `startAngle` + 270, so 135 with the default start. A reversed, empty or full-circle pair, or an angle that is not a finite number, is reported to the host's diagnostics and draws the default dial. |
| `events` | `Omit<ChartEvents, "onLegendChange" \| "onZoomChange">` | no |  |
| `indicator` | `"bar" \| "needle"` | no | How the value is shown (T7): `'needle'` (default) points at it from the pivot; `'bar'` fills a narrower arc inside the band from the dial's start to it, in the on-fill tone that contrasts with the zones beneath. Zones, target and readout are the same in both; the mode is drawing only. |
| `label` | `string` | no | Label displayed below the value. |
| `locale` | `ValuePresentation` | no | Presentation input for axis labels, tooltips, labels and accessibility announcements: a locale code (notation follows the language), or a presentation-context object (`{languageLocale, dateShape?, dateFormat?, timeFormat?, numberFormat?, currencyDisplay?}`) carrying language and notation independently. `dateShape` is the normal human date shape a plain date consumer inherits; an axis that declares its own preset for readability keeps it. Forwarded untouched to the central `@workspace/active-format`; the package never resolves tenant or application settings itself. When omitted, `<ChartDefaults>` supplies it; with neither, the chart throws a configuration error (no `'en'` fallback, active-format D14). Object inputs must be referentially stable across renders. |
| `max` | `number` | no | Maximum end of the scale. Optional — the individual chart component supplies a default when omitted (e.g. `GaugeChart` defaults to `100`). |
| `min` | `number` | no | Minimum end of the scale. Default: `0`. |
| `needleStyle` | `"line" \| "triangle"` | no | Needle style, with `indicator: 'needle'`. Default: 'triangle'. |
| `onAnimationComplete` | `((event: AnimationCompleteEvent) => void)` | no | Fired when a chart animation completes. - `'load'`: initial mount animation finished (or immediately if animation disabled / prefers-reduced-motion is active). - `'update'`: data-update transition finished.  Not triggered by zoom animations (use `onZoomChange`) or tooltip fades. |
| `onExportComplete` | `((result: ChartExportResult) => void)` | no | Fired after a successful export action (PNG/SVG/CSV/PDF), including from the context menu and from imperative `ChartHandle` calls. |
| `onExportError` | `((format: ChartExportFormat, error: unknown) => void)` | no | Fired when an export could not produce its file (W11), from the handle as well as from the context menu. Without it a failed context-menu export is reported as an error diagnostic (`<ChartDefaults diagnostics>`). |
| `onReady` | `(() => void)` | no | Fired exactly once per chart instance, after the first successful mount with valid dimensions and **before** any entrance animation starts. "Ready" means: the SVG is in the DOM, layout has run with real dimensions, and the chart can be queried by integration tests.  Distinct from {@link onAnimationComplete} with `type: 'load'`, which fires *after* the load animation finishes. A chart with `animation={false}` still fires `onReady` — animation state has no effect on readiness.  A new React `key` on the host produces a new component instance and `onReady` fires again. Identity changes of the callback itself after the first fire are ignored (latch is per-instance).  **Consumer requirement — stable from first render.** The latch closes on the first effect run regardless of whether `onReady` was defined at that moment. If `onReady` is initially `undefined` and later resolves to a function, the callback will **never** fire — the latch has already closed with a no-op. Pass a stable reference (typically via `useCallback`) or pass the final function unconditionally from the first render. |
| `replay` | `boolean` | no | A reader may replay the value's entrance (T7): a tap or click at the gauge's pivot, invisible, and Replay animation in the chart's menu. Drawing only: no value, callback, name or export changes. Ignored while the gauge moves; nothing moves under reduced motion or without animation. Default: `false`. |
| `scale` | `ScalarScaleOption` | no | The tick scale (T7, ADR-100): `true` for ticks at automatic round values, `{ticks: [...]}` for exactly these values. Absent or `false`: only the two labelled ends. The ends are always labelled; an interior label gives way where it would meet an end or the target, its tick staying. Drawing only: ticks are in no name, table or CSV. |
| `startAngle` | `number` | no | Where the dial starts, the angle of `min`: degrees clockwise from 12 o'clock, the one radial convention (T2, ADR-095). Default: -135. |
| `t` | `ChartTranslateFn` | no | The host translator for every text the chart shows or announces. When omitted, `<ChartDefaults>` supplies it; with neither, the chart throws a configuration error (no English fallback, ADR-028). |
| `target` | `ScalarTarget` | no | One reference value (T7): a number, or `{value, label}` to name it ("Budget 1.500" in place of "Target 1.500"). Its mark stops at the nearer end beyond the scale; every text keeps the true number and the name and table say it lies above or below the scale. A value that is not finite is neither drawn nor stated (a development diagnostic). |
| `thickness` | `number` | no | Arc thickness as fraction of radius. Default: 0.12. |
| `valueSemantics` | `ChartValueSemantics` | no | What the value means (BC1): unit and precision, declared once with the type the Cartesian charts read (`ChartValueSemantics`). The readout, the scale's end labels, the accessible name and the data table write the value, `min`, `max` and the target in it; the share of the range stays a percentage. `dataLabels.formatter` or `format` still wins; without a declaration the chart presentation's number applies. At rest the readout is `value` itself in every animation mode. CSV keeps the raw number. |
| `width` | `number` | no | Optional fixed width in pixels. Default: fill container. |
| `zoneGradient` | `boolean` | no | Enable smooth gradient between zone colors. Default: false. |
| `zones` | `GaugeZone[]` | no | Color zones (thresholds on the arc). |

## Types

**GaugeChartProps**

```ts
interface GaugeChartProps extends ScalarChartProps {
  contextMenu?: FeatureOption<
    ChartContextMenuOptions<unknown, 'export' | 'replay'>
  >;
  animation?: ScalarAnimationOption<'replay'>;
  indicator?: 'needle' | 'bar';
  replay?: boolean;
  zones?: GaugeZone[];
  label?: string;
  dataLabels?: Pick<DataLabelOptions, 'formatter' | 'format' | 'background'>;
  thickness?: number;
  startAngle?: number;
  endAngle?: number;
  needleStyle?: 'line' | 'triangle';
  zoneGradient?: boolean;
}
```

Props for {@link GaugeChart}. Extends {@link ScalarChartProps} for the
wrapper contract (context-driven defaults via `<ChartDefaults>`, unified
event model, accessibility propagation). Chart-specific fields
(`zones`, `thickness`, `startAngle`, `endAngle`, `needleStyle`,
`zoneGradient`, `label`, `dataLabels`) remain on this interface.

There is no `colors` prop: {@link ScalarChartProps} leaves it out, since no
palette reaches a scalar (LAB-AT21). Gauge zones carry their own explicit
`color` per zone (semantic threshold indicators — typically green/yellow/red)
and are not palette-driven. Needle, needle hub, value and min/max labels
read the foreground, muted-foreground and muted tokens.