One value against its range on a 240° arc: zones that change its tone, a target tick, the value written in the middle.

Web + MobileBetaCharts

Web and mobile — the same component for React and React Native. Beta: its API may still change in a minor version.

When to use

A quota: credits used of a plan, with a warning zone before the limit.
Progress towards a goal with a target: a challenge's escrow against its objective.
A load or a score that has a known range.

When not to use

Several values side by side (a gauge per item takes room and compares badly).Use instead: Bar chart
A value without a meaningful range.Use instead: Sparkline

Installation

Install

npm install @krizaka/charts

Import

import { Gauge } from "@krizaka/charts/gauge";

Examples

Quota

Credits used of a plan: green, then warning past 80 %, danger past the plan.

Credits used this month

Gauge: 41.3K (50K), Nearing the limit.

Credits used this month — data
Category	Value
Credits used this month	41.3K
min	0
max	50K

Goal

A challenge's escrowed amount against its objective, a target tick on the arc.

“Shoot the sunrise from the Mont-Royal”

Challenge in escrow · 6 days left

Gauge: CA$1,860.00 (CA$3,000.00). Objective at CA$2,500.00.

“Shoot the sunrise from the Mont-Royal” — data
Category	Value
“Shoot the sunrise from the Mont-Royal”	CA$1,860.00
min	CA$0.00
max	CA$3,000.00
Objective	CA$2,500.00

Props

One figure against its range — credits used of a plan, a challenge's progress, a load.

Prop	Type	Default	Description
`title`required	`string`	—	What the chart shows, in a few words: its accessible name, and its heading unless `hideTitle`.
`value`required	`number`	—	The value.
`brand`	`BrandId`	—	The brand whose palette the charts use. Without it, a chart follows a `.brand-<id>` ancestor, else Krizaka. Set it when the app loads a brand stylesheet on `:root` (`@krizaka/tokens/brands/orazaka.css`).
`caption`	`string`	—	The words under the value (“of 50 000 credits”).
`className`	`string`	—	A class on the figure (layout: margins, grid placement).
`description`	`ReactNode`	—	A sentence under the title: the period, the unit, the source.
`empty`	`ReactNode`	—	What to show when there is nothing to draw (default: the `empty` label). An `EmptyState` of @krizaka /ui fits.
`error`	`ReactNode`	—	The data could not be loaded: `true` says the default words, a node says yours (a retry button…).
`format`	`ValueFormat`	—	How the value and the range are written.
`height`	`number`	—	The height of the plot in pixels. Default 280 (a sparkline: 32).
`hideTitle`	`boolean`	—	Visually hide the title (it stays the chart's accessible name): a card that already has its heading.
`id`	`string`	—	The id of the figure.
`labels`	`ChartLabelsInput`	—	The words, translated: the buttons, the states, the written summary.
`live`	`boolean`	—	Streaming data (a job queue, an auction): no entrance on updates, no announcement of every new point.
`loading`	`boolean`	—	The data is on its way: a skeleton of the chart, announced once.
`locale`	`Locale`	—	The locale of every figure and date (`"fr-FR"`). Default `"en-US"`.
`max`	`number`	—	The end of the range. Default 100.
`min`	`number`	—	The start of the range. Default 0.
`style`	`CSSProperties`	—	Inline style on the figure (layout only: colours come from the tokens).
`summary`	`"hidden" \| "visible"`	—	The written summary: read by screen readers only (`"hidden"`, default), or shown under the chart (`"visible"`).
`summaryText`	`string`	—	Your own summary instead of the generated one (still read first by screen readers).
`target`	`Threshold`	—	A tick on the arc: the objective.
`tone`	`Tone`	—	The tone of the value without zones. Default `"accent"`.
`zones`	`readonly GaugeZone[]`	—	Coloured zones along the arc: the value takes the tone of the zone it is in.

Accessibility

The gauge is a meter: its name is the title, its value, range and text (value and caption) are exposed.
The zone's tone is never the only signal: its label is in the summary.
The arc fills once, when the gauge comes on screen, and never under reduced motion.

Best practices

Say the range in caption (“of 50,000 credits”): the arc alone is not a number.
Give zones their meaning in label (“Over quota”): it is read in the summary.
Use one gauge per screen at most; a row of figures reads better as stats.

Generated from the code of @krizaka/ui 2.4.0: its meta.ts, its examples and its types.Edit this documentation on GitHub

Gauge