GaugeChart

Container height in pixels. Width is always responsive.

The current value.

Accessible name, description, data table and keyboard navigation. No announcements: it switches <Chart>'s interaction announcements, which this family does not make.

How the gauge moves: its entrance and, as the one scalar that replays, the replay's timing (replay.duration, ADR-100).

Optional className applied to the outer container.

The chart's menu: the host's items, Replay animation while replay is on (T7; features.replay: false leaves it out), then Export.

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.

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.

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.

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 displayed below the value.

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.

Maximum end of the scale. Optional — the individual chart component supplies a default when omitted (e.g. GaugeChart defaults to 100).

Minimum end of the scale. Default: 0.

Needle style, with indicator: 'needle'. Default: 'triangle'.

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.

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.

Where the dial starts, the angle of min: degrees clockwise from 12 o'clock, the one radial convention (T2, ADR-095). Default: -135.

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).

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).

Arc thickness as fraction of radius. Default: 0.12.

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.

Optional fixed width in pixels. Default: fill container.

Enable smooth gradient between zone colors. Default: false.

Color zones (thresholds on the arc).

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.

Fired after a successful export action (PNG/SVG/CSV/PDF), including from the context menu and from imperative ChartHandle calls.

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>).

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 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.