Gauge

Installation

pnpm dlx @mielui/svelte add gauge

npx @mielui/svelte add gauge

yarn dlx @mielui/svelte add gauge

bunx @mielui/svelte add gauge

Usage

value and max set the filled portion; values are clamped between zero and max, which defaults to 100. Give every gauge a label: it is the accessible name, since the center only shows a number. Children replace that number. The default number rolls when the value changes; for custom center content, use the numberShuffle action on the numeric text.

The default diameter is 120px. Set size for compact toolbar meters; the arc and center text scale with it. strokeWidth sets the track thickness, which defaults to 9.75% of the diameter. animation reveals the arc on entry by default, live adds a continuous highlight, and none turns motion off. Reduced motion and themes without motion also turn it off.

<script lang="ts">
    import { Gauge } from '@mielui/svelte/components/gauge';
</script>

<Gauge value={85} label="Context remaining" />
<Gauge value={72} label="Monthly API usage" tone="warning">72%</Gauge>

Changing values

Add files to approach the storage limit, then clear them. The meter transitions from its current value and changes tone near capacity. The label keeps the units explicit for screen readers.

Loading and missing measurements

Set loading while a measurement is being fetched. Pass value={null} when no measurement is available; zero is still a valid value. Gauge keeps its size, draws the matching ring and center text, and announces the state.

<Gauge value={usage} loading={pending} label="Storage used in GB" />
<Gauge value={null} label="Storage used in GB" />

Data and animation states

Compare ready, loading, unavailable, zero, and full measurements. Reveal plays the entry animation; Live highlights the arc continuously without changing its value; None turns motion off. The live highlight pauses offscreen, in hidden tabs, and with reduced motion. Loading and unavailable states keep the same footprint.

Labels

Built-in text is English. Pass a labels object to translate the accessible name Gauge builds while loading (loading), when there is no data (empty), and when there is no label (value). GaugeLabels types it; every key is optional and each one is a function.

<Gauge
    value={72}
    labels={{
        loading: (name) => `Chargement de ${name ?? 'la mesure'}`,
        value: (value, max) => `${value} sur ${max}`
    }}
/>