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 user-tappable control for incrementing or decrementing a numeric value by a fixed step — the canonical glass stepper.
import { Stepper } from "@liquidify/react/stepper"| Prop | Type | Default | Description |
|---|---|---|---|
| children | ReactNode | — | Optional visible label content, rendered next to the capsule in a row — the SwiftUI `label:` closure / `init(_ titleKey:)` analogue (`<Stepper aria-label="Quantity">Quantity</Stepper>`). The accessible name is **not** sourced from here; supply `aria-label` / `aria-labelledby` for the screen-reader name (the segment buttons derive theirs from it). children role: `label`. |
| 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. |
| defaultValue | number | undefined | min` (when bounded), else `0 | Uncontrolled seed for the internal value (ignored once {@link StepperValueProps.value} is supplied). Clamped into `[min, max]`. Absent in callback mode — no value binding exists. |
| disabled | boolean | undefined | — | When `true`, both segments are inert; `aria-disabled` + `data-disabled` on the root; `disabled` on each segment button; `tabIndex={-1}` on the root. |
| labelProps | LabelProps | undefined | — | Per-instance typography override for the visible label, forwarded to the internal {@link Text} (ADR-0028). Token-backed axes only (`variant`, `weight`, `color`, `tint`, `tracking`, …); the HIG default is `variant="body"` / `color="primary"`. Applies only when {@link StepperCommonProps.children} is a string/number — a label element the consumer passes is rendered as-is. |
| max | number | undefined | `undefined` (unbounded) | Upper bound of the value range. Absent in callback mode — there is no range to bound. |
| min | number | undefined | `undefined` (unbounded) | Lower bound of the value range. Absent in callback mode — there is no range to bound. |
| onChange | ((next: number) => void) | undefined | — | Fires with the next clamped value whenever the value changes. Called in both controlled and uncontrolled modes. Absent in callback mode — no value binding exists. |
| onDecrement | (() => void) | undefined | — | See {@link StepperValueProps.onIncrement}. Fires on each `−` press. |
| onEditingChanged | ((editing: boolean) => void) | undefined | — | Fires `true` on segment `pointerdown`, `false` on `pointerup` / `pointercancel` — the SwiftUI `onEditingChanged` analogue. |
| onIncrement | (() => void) | undefined | — | Not on the value branch — callback-only mode is mutually exclusive with a value binding (charter §6). Fires on each `+` press. |
| 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`. |
| step | number | undefined | 1 | Increment / decrement magnitude. A zero, `NaN`, non-finite, or negative `step` coerces to the default `1` (a negative `step` no longer reverses direction). Absent in callback mode — there is no value to step. |
| value | number | undefined | — | Controlled value. Passing this switches Stepper to controlled mode: the rendered value always reflects this (clamped) and the consumer owns it via {@link StepperValueProps.onChange}. Absent in callback mode — no value binding exists. |
Stepper supports the documented keyboard interactions below.
| Name | Value |
|---|---|
| --lq-color-accent | #007aff |
| --lq-color-bg-primary | #ffffff |
| --lq-color-label-primary | Component-defined value |
| --lq-color-label-secondary | Component-defined value |
| --lq-color-label-tertiary | Component-defined value |
| --lq-color-separator | rgba(60, 60, 67, 0.14) |
| --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-opacity-faint | 0.3 |
| --lq-opacity-muted | 0.4 |
| --lq-radius-pill | 9999rem |
| --lq-space- | 0.0625rem0.125rem0.25rem0.5rem0.75rem1rem1.25rem1.5rem2rem2.5rem3rem3.5rem |
| --lq-stepper-capsule-h | Component-defined value |
| --lq-stepper-disabled-opacity | Component-defined value |
| --lq-stepper-divider-w | var(--lq-space-2) |
| --lq-stepper-pad | var(--lq-space-4) |
| --lq-stepper-segment-w | calc(var(--lq-space-40) + var(--lq-space-4)) |