Component catalog
Browse the public controls by interaction purpose. Every result links to generated API facts, accessibility behavior, source, and exhaustive stories.
Browse the public controls by interaction purpose. Every result links to generated API facts, accessibility behavior, source, and exhaustive stories.
A read-only status indicator that conveys either ongoing progress of unknown duration (indeterminate, circular spinner) or a known fraction of completion (determinate, linear bar).
import { ProgressIndicator } from "@liquidify/react/progress-indicator"| Prop | Type | Default | Description |
|---|---|---|---|
| children | ReactNode | — | Optional visible label rendered as a sibling `<span>` to the spinner or bar, styled with the secondary-label token. The SwiftUI `ProgressView("Loading")` / `{ Text("…") }` analogue — the indicator's text content. |
| 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. |
| labelProps | LabelProps | undefined | — | Per-instance typography override for the visible label, forwarded to the internal {@link Text} (ADR-0028). Token-backed axes only; the HIG default is `variant="body"` with `color="secondary"` (circular) / `"primary"` (linear). Applies only when {@link ProgressIndicatorProps.children} is a string/number. |
| 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`. |
| size | ProgressIndicatorSize | undefined | regular | Size of the circular spinner, drawn from the subset `"small" | "regular" | "large"`. The linear bar has a fixed geometry (Apple ships a single bar height) — the `size` prop applies **only to the circular variant**. |
| tint | LiquidTintValue | undefined | blue | System-accent of the determinate fill and the spinner arc — drawn from the restricted {@link LIQUID_COLORS } palette and applied via the `data-tint` attribute selector in CSS (ADR-0024). Per Apple HIG the linear bar fill is system blue by default. |
| value | number | undefined | — | Fractional progress value in `[0, 1]`. Applies **only when the resolved `variant` is `"linear"`** — on `variant="circular"` the value is ignored for ARIA/state purposes and the spinner stays indeterminate. When omitted (`undefined`) the linear indicator is **indeterminate** — the bar shimmers with no fill fraction. When set on a linear indicator, it is **determinate** — the fill encodes the fraction. Out-of-range values are clamped silently. This is a **one-way display prop**: `ProgressIndicator` reads it but never calls back with a new value. |
| variant | "circular" | "linear" | undefined | — | Display variant — `"circular"` renders the spoked spinner; `"linear"` renders the horizontal pill track + fill. When omitted, the variant resolves by `value` presence: `undefined` → `"circular"`, number → `"linear"` (the SwiftUI `.progressViewStyle(.automatic)` analogue). An explicit `variant` overrides which shape renders, but **does not** grant a circular indicator determinacy: `variant="circular"` is always indeterminate, regardless of `value` (audit §7 P2 — a determinate ARIA state over a perpetually-spinning visual disagreed with the eyes). Determinacy is scoped to `variant="linear"` only. |
Progress Indicator preserves the semantics of its content and should be given a clear accessible label when its visible content does not provide one.
| 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-glass- | 440.71.15var(--lq-segmented-control-indicator-blur)calc(var(--lq-glass-material-blur) * 8)var(--lq-shadow-presentational) |
| --lq-hit-target-touch | 2.75rem |
| --lq-progress-bar-h | Component-defined value |
| --lq-progress-pad | Component-defined value |
| --lq-progress-spinner-d-small | var(--lq-space-16) |
| --lq-progress-spinner-period | calc(2 * var(--lq-duration-lazy)) |
| --lq-radius-pill | 9999rem |
| --lq-space- | 0.0625rem0.125rem0.25rem0.5rem0.75rem1rem1.25rem1.5rem2rem2.5rem3rem3.5rem |