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.
is the bare dot indicator for a paged collection — the row of neutral dots that shows how many pages exist, which one is current, and lets the user jump between them.
import { PageControl } from "@liquidify/react/page-control"| Prop | Type | Default | Description |
|---|---|---|---|
| allowsContinuousInteraction | boolean | undefined | true | Enables press-drag scrubbing across the dot row (`UIPageControl`'s continuous interaction): the pressed pointer commits the dot it settles over, dot-to-dot, until release. When `false`, only a discrete dot tap (and the keyboard) can change the page, and `backgroundDisplay="interacting"` never reveals its plate — there is no scrub to reveal it for. |
| aria-label | string | undefined | — | Required accessible name (the tablist renders no visible label). |
| aria-labelledby | string | undefined | — | Required accessible name via reference (alternative to `aria-label`). |
| backgroundDisplay | "automatic" | "always" | "never" | "interacting" | undefined | automatic | Whether/when the frosted backing plate renders. `"always"` keeps it mounted; `"interacting"` mounts it only while the user is scrubbing (a held pointer that has travelled — a plain dot tap never reveals it); `"automatic"` / `"never"` never mount it. `"interacting"` therefore has no effect under `allowsContinuousInteraction={false}`, where no scrub exists. Maps SwiftUI `PageIndexViewStyle.BackgroundDisplayMode.interactive` (the plate reveals only during a live dot interaction) to the React value `"interacting"` — a deliberately different spelling from the removed `GlassMaterial` tier of the same era (D6, ADR-0010), which `material_scale.py` bans from `packages/*` source on an unrelated axis (the glass-surface material, not this presentational display enum). See spec.md `## Variants` for the full SwiftUI → React naming rationale. |
| 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. |
| count required | number | — | Total number of pages (`UIPageControl.numberOfPages`). Required. |
| defaultValue | number | undefined | 0 | Uncontrolled seed for the current page index. |
| disabled | boolean | undefined | false | Disables the whole control. |
| hidesForSinglePage | boolean | undefined | true | Hide the row when `count === 1` under `indexDisplay="automatic"`. |
| id | string | undefined | — | Base id for the deterministic per-dot ids (`${id}-tab-${i}`). |
| indexDisplay | "automatic" | "always" | "never" | undefined | automatic | Whether the dot row renders. |
| onChange | ((index: number) => void) | undefined | — | Fires with the next 0-based index whenever the page changes. |
| 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 | PageControlSize | undefined | regular | Size of the dot row — the `regular · large` subset of the canonical {@link SizedControlProps.sizesize scale} (ADR-0018). Resolved to geometry via `data-size` attribute selectors in `styles.css`; the root stamps `data-size` **unconditionally** (the Button/Toggle pattern), so both values are always addressable in CSS and tests. |
| value | number | undefined | — | Controlled current page index (0-based). |
PageControl supports the documented keyboard interactions below.
| Name | Value |
|---|---|
| --lq-color-fill-tertiary | Component-defined value |
| --lq-color-label-primary | Component-defined value |
| --lq-color-label-tertiary | Component-defined value |
| --lq-duration- | 0ms80ms120ms150ms250ms350ms500ms |
| --lq-ease- | Component-defined value |
| --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-page-control-dot | var(--lq-space-8)var(--lq-space-12) |
| --lq-page-control-dot-active | var(--lq-space-12)var(--lq-space-16) |
| --lq-page-control-dot-gap | var(--lq-space-8)var(--lq-space-12) |
| --lq-page-control-pad | var(--lq-space-4)var(--lq-space-8) |
| --lq-page-control-plate-pad | Component-defined value |
| --lq-radius-pill | 9999rem |
| --lq-space- | 0.0625rem0.125rem0.25rem0.5rem0.75rem1rem1.25rem1.5rem2rem2.5rem3rem3.5rem |