Gauge chart

One value against a range.

<sui-chart-gauge>ChartsStable

About

Display-only gauge: one reading on a 270 degree arc against a range, with an optional target tick and watch band. The value arc is the first ramp step and turns to the accent while the reading sits inside the band. Gauge is the display twin of the Knob input and never takes input itself.

Usage

<sui-chart-gauge heading="Gross margin" subtitle="Target tick 45% · watch band 50 to 60%" value="47.5" min="0" max="60"></sui-chart-gauge> <script type="module"> import { defineCustomElements } from "@shineui/core/loader"; import "@shineui/core/shineui.css"; defineCustomElements(); const el = document.querySelector("sui-chart-gauge"); el.band = [50, 60]; /* [number, number] | undefined */ </script>

import { SuiChartGauge } from "@shineui/react"; import "@shineui/core/shineui.css"; export function Example() { const band = [50, 60]; /* [number, number] | undefined */ return <SuiChartGauge heading="Gross margin" subtitle="Target tick 45% · watch band 50 to 60%" value="47.5" min="0" max="60" band={band} />; }

import { Component } from "@angular/core"; import { SuiChartGauge } from "@shineui/angular"; @Component({ standalone: true, imports: [SuiChartGauge], template: `<sui-chart-gauge heading="Gross margin" subtitle="Target tick 45% · watch band 50 to 60%" value="47.5" min="0" max="60" [band]="band"></sui-chart-gauge>`, }) export class Example { band = [50, 60]; // [number, number] | undefined }

Basic

The gauge is a role="meter", named by an aria-label on the host or the heading, with aria-valuemin, aria-valuemax and aria-valuenow, and the formatted reading as aria-valuetext, so a screen reader hears "47.5%" rather than a raw number. It is display only; Knob is the input twin.

<sui-chart-gauge heading="Gross margin" subtitle="Target tick 45% · watch band 50 to 60%" value="47.5" min="0" max="60" target="45" label="of income · YTD" caption="Above target, below the band we watch for pricing errors"></sui-chart-gauge>

// setup(root): properties and events setup(root) { const el = root.querySelector('sui-chart-gauge'); el.band = [50, 60]; el.format = pct1; }

Watch band

The value arc is --viz-1 until the reading enters the band, then it turns --accent. The band is drawn in --accent-soft and the target tick in --accent-deep.

// setup(root): properties and events setup(root) { for (const el of root.querySelectorAll('sui-chart-gauge')) { el.band = [50, 60]; el.format = pct1; } }

Sizes

diameter is the dial in px: the plot is that wide and 14px shorter. The arc grows with it; the readout, the label and the scale ends keep their type size.

// setup(root): properties and events setup(root) { for (const el of root.querySelectorAll('sui-chart-gauge')) el.format = (v) => v + '%'; }

Formatted readouts

format formats the center readout and both scale ends, so a gauge can carry money or a count instead of a percentage.

// setup(root): properties and events setup(root) { const cash = root.querySelector('#gg-cash'); cash.format = money; const dso = root.querySelector('#gg-dso'); dso.band = [45, 60]; dso.format = days; }

Empty and loading

loading stands a shimmer in for the arc and marks the host aria-busy while the reading is on its way; the frame and its heading stay. A reading past min or max draws the arc at the end it passed and reports that end to a reader, while the readout keeps the raw figure.

API

`<sui-chart-gauge>`

Properties

Property	Attribute	Type	Default	Description
`band`	property only	`[number, number] \| undefined`		Watch band `[lo, hi]` drawn in `--sui-chart-gauge-band`, the soft accent by default. While the reading sits inside it, the value arc paints `--sui-chart-gauge-arc-in-band`, the accent by default. Any CSS color or `var(--token)` works; use a token so the color follows the theme. Property, not attribute.
`caption`	`caption`	`string`string \| undefined		Footer note, separated by a hairline.
`diameter`	`diameter`	`number`	`170`	Diameter of the dial in px: the plot is this wide and 14px shorter, since the arc leaves the bottom of its circle open.
`format`	property only	`((v: number) => string) \| undefined`		Value formatter for the center readout and scale ends. Property, not attribute. Defaults to the figure rounded to a whole number and grouped in the page's locale (`1,250`, `1.250`), with a true minus for a negative.
`heading`	`heading`	`string`string \| undefined		Chart heading (the reference `title` prop, renamed because `title` is a native attribute). With the reading, it names the meter for a reader; an `aria-label` or `aria-labelledby` on the host names the meter instead, and this summary then describes it.
`label`	`label`	`string`string \| undefined		Unit or context line under the value ("of income · YTD"). It stays inside the ring: a line too long for it wraps to two, and past that ends in an ellipsis.
`loading`	`loading`	`boolean`	`false`	The reading is still on its way: a shimmer stands in for the arc, the frame and its heading stay, and the host is `aria-busy`. Reflected, so a page can style the wait.
`max`	`max`	`number`	`100`	Scale end.
`min`	`min`	`number`	`0`	Scale start.
`subtitle`	`subtitle`	`string`string \| undefined		Secondary line under the heading.
`target`	`target`	`number`number \| undefined		Target reading: a tick across the arc in `--sui-chart-gauge-target`, the deep accent by default. Any CSS color or `var(--token)` works; use a token so the color follows the theme.
`value`	`value`	`number`	`0`	Current reading. The arc is a `role="meter"` with `aria-valuemin`, `aria-valuemax` and `aria-valuenow`, and the formatted reading as `aria-valuetext`. The host's own `aria-label` or `aria-labelledby` names the meter where the page gives one, and the heading and the reading then describe it. A reading outside `min` to `max` draws the arc at the end it passed and reports that end to a reader; the readout keeps the raw figure, since a gauge that prints 150% says something a clamped one hides. The value arc paints `--sui-chart-gauge-arc`, the first ramp step by default, over a track in `--sui-chart-gauge-track`, the soft brand by default. Set them on the element or any ancestor. Any CSS color or `var(--token)` works; use a token so the color follows the theme.

Slots

Slot	Description
`header-end`	Controls at the end of the head row, after the heading.

Theming

Every design token this element can render with, read from its own stylesheets and the ones it imports. Set a token on :root or on any ancestor and every use below follows it. The values shown are the ones in the theme you are viewing. The list is read per stylesheet, so an element that imports a shared drawing module lists that module's tokens too, whether or not it paints with all of them.