Gauge

Show a scalar value positioned inside a bounded range (default 0…1) as an arc or bar — a speedometer, a battery, a load meter.

import { Gauge } from "@liquidify/react/gauge"

Overview

Basic Gauge

A focused starting point showing Gauge with its essential configuration.

API

Prop	Type	Default	Description
className	string \| undefined	—	Optional additional CSS class merged into the glass surface class. The supported per-instance customisation seam: override any `--lq-*` custom property from this class's CSS — the token cascade the engine reads (ADR-0004). No raw inline style is involved, so this stays ADR-0003 clean.
currentValueLabel	ReactNode	—	Formatted current value (SwiftUI `currentValueLabel: () -> View`). Rendered visibly on the two marker/accessory styles (leading the line on `accessoryLinear`, large and centred on `accessoryCircular`); not rendered on the two capacity styles (unexercised by the reference). When its content is a plain `string`/`number`, it also drives `aria-valuetext` so assistive tech announces the formatted value (e.g. `"68%"`) rather than a bare number.
label required	ReactNode	—	The primary descriptor (SwiftUI `label: () -> Label`, required) — the accessible name source. Rendered visibly on the two capacity styles (above the bar / centred in the ring); folded into the accessible name only (via a visually-hidden node) on the two marker/accessory styles, where the reference shows no visible `label` glyph. A string/number renders through the `Text` primitive; a `ReactNode` passes through the `TextLabel` guard unwrapped (ADR-0028). A caller supplying a visually-empty `label` (e.g. a bare tint swatch) must also supply an explicit `aria-label` — Gauge does not synthesize a name from `tint` / `variant`.
labelProps	LabelProps \| undefined	—	Per-instance typography override for the primary {@link GaugeProps.label} (ADR-0028, charter §2). Token-backed axes only; spread last onto the internal `Text` so an explicit value wins over the component's computed default. Applies to the visible label on `linearCapacity` (`.lq-gauge-label`) and `accessoryCircularCapacity` (`.lq-gauge-ring-label`). Has no effect on the two marker/accessory styles, where `label` renders visually-hidden.
max	number \| undefined	1	Upper bound of the range (SwiftUI `in: lower...upper`).
maximumValueLabel	ReactNode	—	Upper-bound caption (SwiftUI `maximumValueLabel: () -> View`). Same placement rule as {@link GaugeProps.minimumValueLabel}.
min	number \| undefined	0	Lower bound of the range (SwiftUI `in: lower...upper`).
minimumValueLabel	ReactNode	—	Lower-bound caption (SwiftUI `minimumValueLabel: () -> View`). Rendered only by `accessoryCircular` in the reference, flanking below {@link GaugeProps.currentValueLabel}.
ref	Ref<HTMLDivElement> \| undefined	—	Forwarded ref to the rendered element — the component's native root (or the merged child element on a component that opts into {@link SlottableProps}). Generic over `E` (charter `docs/api-conventions.md` §4 rule 1, default `HTMLElement`) so a component with a polymorphic root (Link's navigation / action mode union, Text's `as`) can instantiate the concrete element per variant instead of leaving every consumer with a widened `Ref<HTMLElement>`. A component that does not narrow simply inherits the `HTMLElement` default — source-compatible with every pre-existing non-generic `extends ControlProps`.
tint	LiquidTintValue \| undefined	—	System-accent of the capacity fill (SwiftUI `.tint(_:)`), drawn from the restricted {@link LIQUID_COLORS } palette. Meaningful only on the two capacity styles (`linearCapacity`, `accessoryCircularCapacity`); the two marker/accessory styles always render monochrome primary and ignore this prop. When omitted on a capacity style, the fill resolves to `--lq-color-accent` (SwiftUI's default, system blue).
value required	number	—	The current value, positioned within `[min, max]`. Out-of-range values are clamped (never extrapolated past the track/arc ends) and the clamped bound — not the raw prop — is what `aria-valuenow` reports.
valueProps	LabelProps \| undefined	—	Per-instance typography override for {@link GaugeProps.currentValueLabel} (charter §2 rule 3). Token-backed axes only; spread last onto the internal `Text` so an explicit value wins over the component's computed default. Applies to `accessoryLinear` (`.lq-gauge-current`) and `accessoryCircular` (`.lq-gauge-arc-current`). {@link GaugeProps.minimumValueLabel} / {@link GaugeProps.maximumValueLabel} carry no override seam.
variant	GaugeStyle \| undefined	linearCapacity	Visual style — verbatim SwiftUI `.gaugeStyle(_:)` member spelling.

Tokens

Name	Value
--lq-color-accent	#007aff
--lq-color-label-primary	Component-defined value
--lq-color-label-secondary	Component-defined value
--lq-color-separator	rgba(60, 60, 67, 0.14)
--lq-color-system-	#ff383c#ff4245#e9152d#ff6165#ff8d28#ff9230#c55300#ffa056#ffcc00#ffd600#a16a00#fedf43
--lq-color-system-blue-default-dark	#0091ff
--lq-color-system-blue-default-light	#0088ff
--lq-duration-standard	250ms
--lq-easing-standard	cubic-bezier(0.25, 0.1, 0.25, 1)
--lq-gauge-arc-sweep	230deg
--lq-gauge-bar-h	var(--lq-space-8)
--lq-gauge-line-h	var(--lq-space-8)
--lq-gauge-pad	var(--lq-space-16)
--lq-gauge-ring-d	var(--lq-space-64)
--lq-gauge-ring-stroke	var(--lq-space-8)
--lq-gauge-ring-sweep	360deg
--lq-gauge-tick-d	var(--lq-gauge-line-h, var(--lq-space-8))
--lq-glass-	440.71.15var(--lq-segmented-control-indicator-blur)calc(var(--lq-glass-material-blur) * 8)var(--lq-shadow-presentational)
--lq-radius-pill	9999rem
--lq-space-	0.0625rem0.125rem0.25rem0.5rem0.75rem1rem1.25rem1.5rem2rem2.5rem3rem3.5rem

Component catalog

Browse the public controls by interaction purpose. Every result links to generated API facts, accessibility behavior, source, and exhaustive stories.

API

Prop	Type	Default	Description
className	string \| undefined	—	Optional additional CSS class merged into the glass surface class. The supported per-instance customisation seam: override any `--lq-*` custom property from this class's CSS — the token cascade the engine reads (ADR-0004). No raw inline style is involved, so this stays ADR-0003 clean.
currentValueLabel	ReactNode	—	Formatted current value (SwiftUI `currentValueLabel: () -> View`). Rendered visibly on the two marker/accessory styles (leading the line on `accessoryLinear`, large and centred on `accessoryCircular`); not rendered on the two capacity styles (unexercised by the reference). When its content is a plain `string`/`number`, it also drives `aria-valuetext` so assistive tech announces the formatted value (e.g. `"68%"`) rather than a bare number.
label required	ReactNode	—	The primary descriptor (SwiftUI `label: () -> Label`, required) — the accessible name source. Rendered visibly on the two capacity styles (above the bar / centred in the ring); folded into the accessible name only (via a visually-hidden node) on the two marker/accessory styles, where the reference shows no visible `label` glyph. A string/number renders through the `Text` primitive; a `ReactNode` passes through the `TextLabel` guard unwrapped (ADR-0028). A caller supplying a visually-empty `label` (e.g. a bare tint swatch) must also supply an explicit `aria-label` — Gauge does not synthesize a name from `tint` / `variant`.
labelProps	LabelProps \| undefined	—	Per-instance typography override for the primary {@link GaugeProps.label} (ADR-0028, charter §2). Token-backed axes only; spread last onto the internal `Text` so an explicit value wins over the component's computed default. Applies to the visible label on `linearCapacity` (`.lq-gauge-label`) and `accessoryCircularCapacity` (`.lq-gauge-ring-label`). Has no effect on the two marker/accessory styles, where `label` renders visually-hidden.
max	number \| undefined	1	Upper bound of the range (SwiftUI `in: lower...upper`).
maximumValueLabel	ReactNode	—	Upper-bound caption (SwiftUI `maximumValueLabel: () -> View`). Same placement rule as {@link GaugeProps.minimumValueLabel}.
min	number \| undefined	0	Lower bound of the range (SwiftUI `in: lower...upper`).
minimumValueLabel	ReactNode	—	Lower-bound caption (SwiftUI `minimumValueLabel: () -> View`). Rendered only by `accessoryCircular` in the reference, flanking below {@link GaugeProps.currentValueLabel}.
ref	Ref<HTMLDivElement> \| undefined	—	Forwarded ref to the rendered element — the component's native root (or the merged child element on a component that opts into {@link SlottableProps}). Generic over `E` (charter `docs/api-conventions.md` §4 rule 1, default `HTMLElement`) so a component with a polymorphic root (Link's navigation / action mode union, Text's `as`) can instantiate the concrete element per variant instead of leaving every consumer with a widened `Ref<HTMLElement>`. A component that does not narrow simply inherits the `HTMLElement` default — source-compatible with every pre-existing non-generic `extends ControlProps`.
tint	LiquidTintValue \| undefined	—	System-accent of the capacity fill (SwiftUI `.tint(_:)`), drawn from the restricted {@link LIQUID_COLORS } palette. Meaningful only on the two capacity styles (`linearCapacity`, `accessoryCircularCapacity`); the two marker/accessory styles always render monochrome primary and ignore this prop. When omitted on a capacity style, the fill resolves to `--lq-color-accent` (SwiftUI's default, system blue).
value required	number	—	The current value, positioned within `[min, max]`. Out-of-range values are clamped (never extrapolated past the track/arc ends) and the clamped bound — not the raw prop — is what `aria-valuenow` reports.
valueProps	LabelProps \| undefined	—	Per-instance typography override for {@link GaugeProps.currentValueLabel} (charter §2 rule 3). Token-backed axes only; spread last onto the internal `Text` so an explicit value wins over the component's computed default. Applies to `accessoryLinear` (`.lq-gauge-current`) and `accessoryCircular` (`.lq-gauge-arc-current`). {@link GaugeProps.minimumValueLabel} / {@link GaugeProps.maximumValueLabel} carry no override seam.
variant	GaugeStyle \| undefined	linearCapacity	Visual style — verbatim SwiftUI `.gaugeStyle(_:)` member spelling.

Component catalog

Gauge

Overview

Basic Gauge

API

Guidelines

Accessibility

Tokens

Liquid material

Typed API

Accessible by default

Component catalog

Gauge

Overview

Basic Gauge

API

Guidelines

Accessibility

Tokens

Liquid material

Typed API

Accessible by default