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 persistent, in-flow bar that surfaces a short status or notification without blocking the page: a status glyph, a title, an optional secondary message, an optional row of trailing actions, and an optional dismiss control.
import { Banner } from "@liquidify/react/banner"| Prop | Type | Default | Description |
|---|---|---|---|
| actions | readonly BannerAction[] | undefined | — | Trailing action row, keyed by each action's stable `id`. |
| 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. |
| defaultOpen | boolean | undefined | true | Uncontrolled seed for the open state — a banner passed no `open` renders visible. |
| dismissible | boolean | undefined | true | Renders the trailing `xmark` dismiss control when `true`. |
| dismissIcon | ReactNode | — | Custom dismiss glyph — an SF-Symbol-style name string or a node (the `Image(systemName:)` analogue, mirroring {@link BannerProps.icon}); when omitted the default self-drawn `xmark` cross renders. Purely visual: the control keeps its `aria-label` ({@link BannerProps.dismissLabel}) either way. |
| dismissLabel | string | undefined | Dismiss | Accessible name override for the dismiss control. |
| icon | ReactNode | — | Leading status glyph. An SF-Symbol-style name string or a node; when omitted a status-default glyph is derived from {@link BannerProps.status}. |
| id | string | undefined | — | Native `id` forwarded to the bar root (charter §8: no silently-discarded inherited props). |
| items | readonly ReactNode[] | undefined | — | Optional bulleted supporting points. Each item receives the same native Banner message typography configured through `messageProps`. |
| labelProps | LabelProps | undefined | — | Per-instance typography override for the title, forwarded to the internal `Text` (ADR-0028). Spread last over the computed default. |
| live | boolean | undefined | true | When `false`, the banner is a static, labelled `role="region"` (not a live region) — for banners present at page load rather than dynamically raised. |
| material | "frosted" | "regular" | "clear" | undefined | enclosing `<Material default>`, else `"regular"` | Material of the glass surface — `frosted · regular · clear` (§06). Forwarded to the engine, which resolves the chain `prop ?? <Material default> ?? "regular"`, so a bare surface inherits the enclosing provider default. |
| message | ReactNode | — | Optional secondary copy; the `aria-describedby` target. |
| messageProps | LabelProps | undefined | — | Per-instance typography override for the message, forwarded to the internal `Text` (ADR-0028). Spread last over the `footnote`/`secondary` default. |
| onOpenChange | ((open: boolean) => void) | undefined | — | Fires with the next boolean on every close path (dismiss, or `closesOnPress` action). |
| open | boolean | undefined | — | Controlled open state. Passing it switches Banner to controlled mode. |
| perf | "low" | "high" | undefined | derived from `<Backdrop type>`, else `"low"` | Perf budget of the glass surface (ADR-0006/0007). Forwarded to the engine as `data-glass-perf`; `"high"` opts this surface into the edge-lensing filter. When omitted, derives from the enclosing `<Backdrop type>` (§04). |
| ref | Ref<HTMLDivElement> | undefined | — | Forwarded ref to the rendered element — the bar `<div>` carrying the a11y role; attached while `open` and `null` while dismissed. |
| status | BannerStatus | undefined | info | Severity axis — selects the default glyph + accent colour (glyph/edge only, never a full-surface wash, ADR-0019) and the derived a11y `role`. |
| title required | ReactNode | — | The bar's primary text — required, the `aria-labelledby` target. |
Banner 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-alert-control-fill | light-dark( var(--lq-color-system-gray-2-default-light), var(--lq-color-system-gray-3-default-dark) ) |
| --lq-banner-gap | var(--lq-space-12) |
| --lq-banner-pad | var(--lq-space-16) |
| --lq-color-action-destructive | #ff3b30 |
| --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-blue-default | Component-defined value |
| --lq-color-system-green-default | Component-defined value |
| --lq-color-system-orange-default | Component-defined value |
| --lq-color-system-red-default | Component-defined value |
| --lq-duration- | 0ms80ms120ms150ms250ms350ms500ms |
| --lq-easing- | cubic-bezier(0.25, 0.1, 0.25, 1)cubic-bezier(0, 0, 0.2, 1)cubic-bezier(0.4, 0, 1, 1)cubic-bezier(0.175, 0.885, 0.32, 1.275)cubic-bezier(0.25, 0.46, 0.45, 0.94) |
| --lq-glass- | 440.71.15var(--lq-segmented-control-indicator-blur)calc(var(--lq-glass-material-blur) * 8)var(--lq-shadow-presentational) |
| --lq-opacity-muted | 0.4 |
| --lq-radius- | 0.25rem0.375rem0.5rem0.625rem0.875rem1.125rem1.375rem9999rem |
| --lq-radius-pill | 9999rem |
| --lq-shadow-presentational | var(--lq-shadow-ambient-3) |
| --lq-space- | 0.0625rem0.125rem0.25rem0.5rem0.75rem1rem1.25rem1.5rem2rem2.5rem3rem3.5rem |