Studio
2

Gauge

Installation

pnpm dlx @mielui/svelte add gauge

Usage

The default diameter is 120px. Set size explicitly 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. The track and colored arc share the same thickness. Values are clamped between zero and max. A nonpositive or nonfinite max falls back to 100, and nonfinite values display zero. Entry and value changes animate unless the theme disables motion or the user requests reduced motion. Set animation="live" for a continuous highlight, or animation="none" to disable entry and update motion.

Use value and max for the filled portion. Provide label to name the meter for screen-reader users; children can replace the default numeric center text. The default number rolls with value changes. For custom center content, use the numberShuffle action on the numeric text.

import { Gauge } from '@mielui/svelte/components/gauge';

<Gauge value={85} label="Context remaining" />
<Gauge value={72} max={100} 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 a null value when no measurement is available; zero remains a valid value. Gauge keeps its size, renders the appropriate ring and center label, and announces the state. No wrapper or placeholder is needed.

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

Examples

Compact and detailed

Usage limit

Data and animation states

API reference

Gauge

Displays a value as a filled arc.

Prop Type Default
value Required number | null

The bounded quantity shown by the filled arc. Pass null when no measurement is available.

 —
loading boolean | undefined

Show a loading ring while the measurement is being fetched.

 false
max number | undefined 100
label string | undefined

Describes the quantity, such as "Context remaining" or "Monthly API usage".

 —
size number | undefined

Diameter in pixels. Defaults to 120; use an explicit size for inline meters.

 120
strokeWidth number | undefined

Track and arc thickness in pixels. Defaults to 9.75% of the diameter, with a 3px minimum.

 —
animation "none" | "reveal" | "live" | undefined

Reveal the arc, highlight it continuously, or disable animation.

 'reveal'
tone GaugeTone | undefined 'primary'
class string | undefined —
children Snippet<[]> | undefined —