All components (204)

Gauge

Surfaces · Gauge

What it is and when to use it

How much there is of something: space used, stock, quota consumed. It is a level that is just there, whether it goes up or down: the color is decided by the thresholds and the value is written as well as painted, because a bar that turns red does not say how much is left.

When to use it

Quotas and occupancy: photo space, the month's shipments, the stock of a reference.
By default the color stays accent up to 75%, changes to warning from 75% and to error from 90%. thresholds changes the bands (the order in which they are given does not matter); tone fixes a color and disables them.
min and max (0 and 100 by default) set the range of value; hint adds a help line below the bar.
valueText to say it in your own words ("3.2 GB of 10 GB"): it receives the value and the percentage. format changes how the number is written; careful: with format, value is written as is, not the percentage.

When not to

A task that advances and ends: Progress.
Comparing several quantities with each other: BarChart.
A single figure with its change: Stat.

Keyboard: it is not focusable.

Accessibility: role="meter" with the label as its name, aria-valuenow, aria-valuemin and aria-valuemax, and aria-valuetext with the same as what is seen written. It carries role="meter" and nothing else: a composite role such as meter progressbar makes axe consider aria-valuenow and company not allowed.

Fine-tuning: no variables of its own: adjust it with the classes amset-gauge, amset-gauge--sm (5 px bar instead of 8) and amset-gauge__padding--<tone> / amset-gauge__value--<tone>, with the same value as tone.

Context: the number is written in the language of LocaleProvider (or AmsetProvider).

What it looks like

Delete old photos or upgrade your plan.

<Gauge label="Monthly shipping quota" value={68} />
<Gauge label="Photo area" value={96} hint="Delete old photos or upgrade your plan." />
<Gauge
  label="Today's orders prepared"
  value={40}
  size="sm"
  thresholds={[{ from: 0, tone: 'error' }, { from: 50, tone: 'warning' }, { from: 90, tone: 'success' }]}
/>

Props

Import it with import { Gauge } from '@amset/ui'. Required props are marked.

Prop	Type	What it does
`label`required	`string`	What is being measured: "Space used", "Stock". Required.
`value`required	`number`	—
`className`	`string`	Merged with the library classes; it does not replace them.
`format`	`Intl.NumberFormatOptions`	How the value is written. By default, percentage.
`hint`	`string`	—
`max`	`number`	—
`min`	`number`	—
`size`	`"sm" \| "md"`	—
`thresholds`	`readonly GaugeThreshold[]`	Changes color when passing certain percentages.
`tone`	`"neutral" \| "accent" \| "secondary" \| "tertiary" \| "info" \| "success" \| "warning" \| "error"`	Sets the tone and disables the thresholds. `neutral` is the gray of the secondary ink.
`valueText`	`(value: number, percent: number) => string`	Custom text instead of the number: "3.2 GB of 10 GB".

It also accepts the attributes of the element it renders: className, style, data-*, aria-* and its events.

In the test bench

Every state and variant, to try one at a time, on its page at ui.amset.tech: