{"slug":"gauge","name":"Gauge","packageName":"@liquidify/react","category":"presentational","maturity":"experimental","summary":"Show a scalar value positioned inside a bounded range (default 0…1) as an arc or bar — a speedometer, a battery, a load meter.","importPath":"@liquidify/react/gauge","sourcePath":"packages/@liquidify/react/src/components/gauge/gauge.tsx","specPath":"packages/@liquidify/react/src/components/gauge/spec.md","docsPath":"../liquidify-page/content/component-source/gauge.md","documentationStatus":"draft","storyIds":["presentational-gauge--default"],"additionalExports":["GaugeStyle","LiquidColor","LiquidTintValue","TintableControlProps"],"anatomy":[],"props":[{"name":"className","type":"string | undefined","required":false,"description":"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.","declaredIn":"packages/@liquidify/react/src/liquid-component-props.ts"},{"name":"currentValueLabel","type":"ReactNode","required":false,"description":"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.","declaredIn":"packages/@liquidify/react/src/components/gauge/gauge.tsx"},{"name":"label","type":"ReactNode","required":true,"description":"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`.","declaredIn":"packages/@liquidify/react/src/components/gauge/gauge.tsx"},{"name":"labelProps","type":"LabelProps | undefined","required":false,"description":"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.","declaredIn":"packages/@liquidify/react/src/components/gauge/gauge.tsx"},{"name":"max","type":"number | undefined","required":false,"description":"Upper bound of the range (SwiftUI `in: lower...upper`).","defaultValue":"`1`","declaredIn":"packages/@liquidify/react/src/components/gauge/gauge.tsx"},{"name":"maximumValueLabel","type":"ReactNode","required":false,"description":"Upper-bound caption (SwiftUI `maximumValueLabel: () -> View`). Same placement rule as {@link GaugeProps.minimumValueLabel}.","declaredIn":"packages/@liquidify/react/src/components/gauge/gauge.tsx"},{"name":"min","type":"number | undefined","required":false,"description":"Lower bound of the range (SwiftUI `in: lower...upper`).","defaultValue":"`0`","declaredIn":"packages/@liquidify/react/src/components/gauge/gauge.tsx"},{"name":"minimumValueLabel","type":"ReactNode","required":false,"description":"Lower-bound caption (SwiftUI `minimumValueLabel: () -> View`). Rendered only by `accessoryCircular` in the reference, flanking below {@link GaugeProps.currentValueLabel}.","declaredIn":"packages/@liquidify/react/src/components/gauge/gauge.tsx"},{"name":"ref","type":"Ref<HTMLDivElement> | undefined","required":false,"description":"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`.","declaredIn":"packages/@liquidify/react/src/liquid-component-props.ts"},{"name":"tint","type":"LiquidTintValue | undefined","required":false,"description":"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).","declaredIn":"packages/@liquidify/react/src/components/gauge/gauge.tsx"},{"name":"value","type":"number","required":true,"description":"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.","declaredIn":"packages/@liquidify/react/src/components/gauge/gauge.tsx"},{"name":"valueProps","type":"LabelProps | undefined","required":false,"description":"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.","declaredIn":"packages/@liquidify/react/src/components/gauge/gauge.tsx"},{"name":"variant","type":"GaugeStyle | undefined","required":false,"description":"Visual style — verbatim SwiftUI `.gaugeStyle(_:)` member spelling.","defaultValue":"`\"linearCapacity\"`","declaredIn":"packages/@liquidify/react/src/components/gauge/gauge.tsx"}],"swiftUIMap":[{"swiftUI":"`Gauge(value:label:)`","react":"`value: number` (required) + `label: ReactNode` (required)","notes":"Display-only — no `onChange` (ADR-0015 does not apply; see Interaction).","relationship":"direct"},{"swiftUI":"`in: lower...upper`","react":"`min?: number` / `max?: number`","notes":"Default `min=0, max=1` (SwiftUI implicit `0...1`).","relationship":"direct"},{"swiftUI":"`label: () -> Label`","react":"`label: ReactNode` (required)","notes":"Primary descriptor; accessible name (see Accessibility). String/number renders through the `Text` primitive; a `ReactNode` passes through the `TextLabel` guard unwrapped (ADR-0028).","relationship":"direct"},{"swiftUI":"`currentValueLabel: () -> View`","react":"`currentValueLabel?: ReactNode`","notes":"Formatted current value. Placement is `variant`-dependent: leading of the line (`accessoryLinear`), centred (`accessoryCircular`/`accessoryCircularCapacity`); absent on `linearCapacity` in the reference.","relationship":"direct"},{"swiftUI":"`minimumValueLabel: () -> View`","react":"`minimumValueLabel?: ReactNode`","notes":"Rendered only by `accessoryCircular` in the reference (flanks below the current-value label).","relationship":"direct"},{"swiftUI":"`maximumValueLabel: () -> View`","react":"`maximumValueLabel?: ReactNode`","notes":"Same placement rule as `minimumValueLabel`.","relationship":"direct"},{"swiftUI":"`.gaugeStyle(.linearCapacity)` etc.","react":"`variant?: \"linearCapacity\" | \"accessoryCircularCapacity\" | \"accessoryLinear\" | \"accessoryCircular\"`","notes":"`.<control>Style(_:)` → library-wide `variant` (Toggle/Picker/Progress convention); values are verbatim SwiftUI member spelling; default `\"linearCapacity\"` (SwiftUI's `.automatic` resolves to this on iOS).","relationship":"direct"},{"swiftUI":"`.tint(Color)`","react":"`tint?: LiquidTintValue` (via `TintableControlProps`)","notes":"Drives the capacity-fill hue; the restricted 13-colour palette plus the `\"accent\"` system-default sentinel (ADR-0023/0024). No effect on `accessoryLinear` / `accessoryCircular` (see above).","relationship":"direct"},{"swiftUI":"`.tint(Gradient)`","react":"— (Out of scope)","notes":"Not authored in the demo; Apple's built-in per-tint arc gradient (desaturated→saturated) is likewise not reproduced — ship a solid fill (see Tokens, Out of scope).","relationship":"direct"},{"swiftUI":"`markedValueLabels:`","react":"— (Out of scope)","notes":"Not exercised; omitted from v1.","relationship":"direct"},{"swiftUI":"`Text(value, format:)` inside a label closure","react":"(caller's responsibility)","notes":"Value formatting is a *label content* concern, not a Gauge prop — the caller formats `currentValueLabel`'s content itself.","relationship":"direct"},{"swiftUI":"*(no analogue — web-only)*","react":"`labelProps?: LabelProps`","notes":"Per-instance typography override seam (ADR-0028, charter §2), spread **last** onto the primary `label` `Text` (`linearCapacity`'s `.lq-gauge-label`, `accessoryCircularCapacity`'s `.lq-gauge-ring-label`) so an explicit value wins over the component's computed default.","relationship":"web-only"},{"swiftUI":"*(no analogue — web-only)*","react":"`valueProps?: LabelProps`","notes":"Secondary typography-override seam (charter §2 rule 3), spread **last** onto the `currentValueLabel` `Text` (`accessoryLinear`'s `.lq-gauge-current`, `accessoryCircular`'s `.lq-gauge-arc-current`). `minimumValueLabel`/`maximumValueLabel` intentionally have **no** override seam — the charter names only `labelProps` + `valueProps` for Gauge.","relationship":"web-only"}],"tokens":["--lq-color-accent","--lq-color-label-primary","--lq-color-label-secondary","--lq-color-separator","--lq-color-system-","--lq-color-system-blue-default-dark","--lq-color-system-blue-default-light","--lq-duration-standard","--lq-easing-standard","--lq-gauge-arc-sweep","--lq-gauge-bar-h","--lq-gauge-line-h","--lq-gauge-pad","--lq-gauge-ring-d","--lq-gauge-ring-stroke","--lq-gauge-ring-sweep","--lq-gauge-tick-d","--lq-glass-","--lq-radius-pill","--lq-space-"],"keyboard":[],"variants":["accessoryCircular","accessoryCircularCapacity","accessoryLinear","linearCapacity"],"variantPages":[]}