Components

A box that constrains its content to a width-to-height ratio via CSS aspect-ratio.A box that constrains its content to a width-to-height ratio via CSS aspect-ratio. ratio is a curated preset set of modifier classes (1/1, 4/3, 3/2, 16/9, 21/9 and their portrait inverses); a bespoke ratio comes from overriding --primitiv-aspect-ratio in a stylesheet.

The escape hatch — a bare polymorphic element with no visual opinion.The escape hatch — a bare polymorphic element with no visual opinion. Exists so a consumer has something to attach a custom property or a one-off style to without reaching for a raw <div>.

A single- or both-axis Flexbox centring box.A single- or both-axis Flexbox centring box.

A centred, max-width content column with token-bound inline gutters.A centred, max-width content column with token-bound inline gutters. size caps the width against the breakpoint scale and gutter sets the inline padding — responsive (the default) escalates it at the md and lg breakpoints, the fixed steps pin one value at every width. No inline styles: both props are curated presets.

A separator between content sections — a <span role="separator"> whose...A separator between content sections — a <span role="separator"> whose aria-orientation drives a horizontal or vertical rule.

A CSS Grid container.A CSS Grid container. columns takes a count or a mobile-first per-breakpoint map, gap the spacing (a density-scaled Context token per step), and align/justify how each item sits within its cell. No inline styles: the per-breakpoint column counts resolve to modifier classes, so the responsive behaviour is correct in server-rendered markup on the first paint.

A flex: 1 0 0 blank element for pushing flex siblings apart — toolbar left/right...A flex: 1 0 0 blank element for pushing flex siblings apart — toolbar left/right groups, card footers, nav bars.

A Flexbox stack — direction picks the axis, gap the spacing (a density-scaled...A Flexbox stack — direction picks the axis, gap the spacing (a density-scaled Context token per step), wrap whether the row may break onto additional lines, and align/justify the alignment, all as modifier classes. No inline styles: the alignment props are curated presets, not raw CSS keywords.

A clickable action — a button, or a link styled as one via asChild.A clickable action — a button, or a link styled as one via asChild.

One primary action welded to a chevron trigger that opens a menu of related...One primary action welded to a chevron trigger that opens a menu of related alternatives, bound into a single role="group" widget.

A tri-state checkbox with an optional inline label — an independent on/off (or mixed)...A tri-state checkbox with an optional inline label — an independent on/off (or mixed) form selection.

A card/tile-shaped checkbox — the whole bordered surface is the interactive element...A card/tile-shaped checkbox — the whole bordered surface is the interactive element, not a small control plus a separate label. Composes the headless CheckboxCard primitive (role="checkbox", tri-state unchecked/checked/indeterminate). Sized xs–xl; data-density scales each size further.

A form-field wrapper — coordinates a label, control, description, and error message and...A form-field wrapper — coordinates a label, control, description, and error message and cascades id / validity / disabled / required to the control it wraps.

A single-line text input — the framed field consumers type into.A single-line text input — the framed field consumers type into.

A framed control with leading / trailing adornment slots — wraps an Input for icons...A framed control with leading / trailing adornment slots — wraps an Input for icons, prefixes, clear buttons, and reveal toggles.

A single native radio input with an optional inline label, grouped with a shared name.A single native radio input with an optional inline label, grouped with a shared name.

A card/tile-shaped radio item — the whole bordered surface is the interactive element...A card/tile-shaped radio item — the whole bordered surface is the interactive element, not a small control plus a separate label. Composes the headless RadioCard primitive (RadioCard.Root is role="radiogroup" with no visual anatomy of its own; RadioCard.Item is role="radio"). Sized xs–xl; data-density scales each size further.

A single-select segmented control — a linear strip of segments where exactly one is...A single-select segmented control — a linear strip of segments where exactly one is selected. The selected segment is brand-filled; the rest are secondary.

A draggable, keyboard-accessible control for selecting one value (or a range) along a...A draggable, keyboard-accessible control for selecting one value (or a range) along a track.

An on/off toggle with an optional inline label — a native switch input for an immediate...An on/off toggle with an optional inline label — a native switch input for an immediate binary setting.

A multi-line text input — the framed field consumers type longer content into.A multi-line text input — the framed field consumers type longer content into.

An editable text field with a filtered popup listbox, implementing the WAI-ARIA APG...An editable text field with a filtered popup listbox, implementing the WAI-ARIA APG combobox pattern. The control is Input verbatim — same framed-control/{size}/* geometry, same states — wrapped so a trailing chevron can sit beside the field, and the popup is a floating panel at elevation/overlay whose rows resolve the shared dropdown tokens, so a combobox listbox and a menu are the same surface. Filtering is consumer-owned: there is no filter prop. Keyboard, virtual-focus cursor, the query/value split and the open state all belong to the headless primitive.

A persistently-visible list of selectable options implementing the WAI-ARIA APG listbox...A persistently-visible list of selectable options implementing the WAI-ARIA APG listbox pattern. Unlike select, this list is always on screen with no trigger and no popup, and its cursor is a virtual-focus position (aria-activedescendant on the root, data-highlighted on the option) rather than DOM focus — which is what lets a separate control, such as a search input or a command palette's text field, hold focus and drive the list at the same time. Framed like a form control on Input's geometry, with rows resolving the shared dropdown tokens so a listbox and a menu are the same surface. Keyboard, typeahead, cursor and selection are owned by the headless primitive.

A horizontal strip of vertical lists where selecting a node reveals its children in the...A horizontal strip of vertical lists where selecting a node reveals its children in the next column — the macOS Finder column view, with drag/keyboard-resizable columns and an optional preview pane.

A single-select control with two render paths behind one API: a rich Popover-API...A single-select control with two render paths behind one API: a rich Popover-API listbox (the default) whose options carry icons, badges and a selected mark, or a native <select> for flat, OS-native cases. The rich control is a framed field on the same geometry as Input; its panel and rows resolve the shared dropdown tokens, so a Select listbox and a Dropdown menu are the same surface. Positioned with CSS anchor positioning, wired by the component itself; keyboard, typeahead, focus and form submission are owned by the headless primitive.

A hierarchical list of expandable branches and selectable leaves — the WAI-ARIA tree...A hierarchical list of expandable branches and selectable leaves — the WAI-ARIA tree view, with connector guide lines and an optional breadcrumb of the selected node's ancestry.

A <blockquote> with a left-stroke accent bar and an optional attribution line.A <blockquote> with a left-stroke accent bar and an optional attribution line. tone picks the bar colour (default | accent); size scales the quote and citation type together.

A block of source code — a bordered, tinted surface with mono type, an optional...A block of source code — a bordered, tinted surface with mono type, an optional filename/copy header, an optional line-number gutter, and Prism syntax highlighting themed from tokens. Sized xs–xl; data-density scales the padding. Compound subcomponents (CodeBlock.Tabs/Header/List/Trigger/Content/Copy) add a tabbed variant that composes the headless Tabs primitive and reuses the tabs component's classes.

A <dl> compound — one <dt> (fixed SemiBold) + one <dd> per pair.A <dl> compound — one <dt> (fixed SemiBold) + one <dd> per pair. layout picks stacked (dt above dd, dd indented) or inline (dt : dd side by side in a two-column grid), matching the two layouts in the Figma component set. Consumers compose multiple Term/Details pairs to form a full description list. row-gap/column-gap/details-indent are density-scaled Context tokens; inline's pair-to-pair gap reuses List's item-gap directly, matching the Figma binding.

A <figure>/<figcaption> pairing that wraps self-contained content (an image...A <figure>/<figcaption> pairing that wraps self-contained content (an image, illustration, chart, code listing, table) with an optional caption in one of three positions — below (default), above, or overlaid on the media. size scales the caption's type off the body/{size} ramp (the media is size-independent, as in Figma); the caption's own align matches Figma's Figcaption Align axis.

Inline code — a <code> fragment set in the mono face on a tinted, hairline-bordered...Inline code — a <code> fragment set in the mono face on a tinted, hairline-bordered chip. Sized xs–xl so a snippet tracks the surrounding text; data-density scales each size further.

A <kbd> fragment set in the mono face on a raised, bordered key cap — the...A <kbd> fragment set in the mono face on a raised, bordered key cap — the physical-keycap sibling of Inline Code. Sized xs–xl so a shortcut tracks the surrounding text; data-density scales each size further.

A <ul>/<ol> with custom, token-coloured markers and a controllable item gap, marker gap...A <ul>/<ol> with custom, token-coloured markers and a controllable item gap, marker gap and indent — the styled counterpart to the bare list styles in primitiv.reset.

A flow-rhythm container — applies the .primitiv-flow context so every direct child...A flow-rhythm container — applies the .primitiv-flow context so every direct child gets density-scoped vertical spacing via a one-directional owl. Zero behaviour; renders a semantic element, composing the consumer's own element via asChild.

A large, centred editorial quote — no accent bar, no attribution, distinct from...A large, centred editorial quote — no accent bar, no attribution, distinct from Blockquote. Rides the existing heading/* type scale; an optional decorative open-quote mark.

A pre-arranged Modal for confirming or cancelling a single action — title, body slot...A pre-arranged Modal for confirming or cancelling a single action — title, body slot, and a Cancel/Confirm footer, with the Confirm button's tone following the action (primary, or danger for a destructive one). Composes the registry modal and button components directly rather than introducing new dialog anatomy.

An accessible drawer — a Modal dialog built on the native <dialog> element that...An accessible drawer — a Modal dialog built on the native <dialog> element that slides in from a screen edge (top, right, bottom, or left).

A menu-button dropdown built on the native HTML Popover API — a bordered...A menu-button dropdown built on the native HTML Popover API — a bordered, shadow-defined panel of selectable rows (plain items, checkbox/radio items, submenus), grouped with labels and separators. Positioned with CSS anchor positioning; keyboard, typeahead, and focus are owned by the headless primitive.

An accessible modal dialog built on the native <dialog> element — a fixed-width...An accessible modal dialog built on the native <dialog> element — a fixed-width surface with an optional dimmed backdrop (WAI-ARIA Modal Dialog pattern).

A non-modal floating panel anchored to a trigger, built on the native HTML Popover API...A non-modal floating panel anchored to a trigger, built on the native HTML Popover API — a borderless, shadow-defined surface with a pointer arrow, positioned with CSS anchor positioning across all twelve placements.

A deferred, non-modal label anchored to a trigger (hover / focus).A deferred, non-modal label anchored to a trigger (hover / focus). A flat bubble with a pointer arrow, in two tones — a high-contrast dark bubble (default) or a surface-coloured one (inverted).

An assertive banner for high-priority, time-sensitive messages — a tone-matched icon...An assertive banner for high-priority, time-sensitive messages — a tone-matched icon, an optional title, a description, and an optional dismiss button. Composes the headless Alert primitive (role="alert") for the message and the registry Button (ghost variant) for the dismiss affordance. Sized xs–xl; data-density scales each size further.

The placeholder shown when a collection, search, or view has no content — a decorative...The placeholder shown when a collection, search, or view has no content — a decorative media slot, a headline, supporting copy, and recovery actions, centred in the space it fills. Composes the headless EmptyState primitive (role="status", a polite live region). Sized xs–xl; data-density scales each size further.

A progress bar — a track with a fill that reports completion, or an animated...A progress bar — a track with a fill that reports completion, or an animated indeterminate state when the ratio is unknown. intent picks the fill colour (primary/secondary/danger), matching the Figma set; the track stays neutral in every intent.

A vertically stacked set of collapsible sections — hairline rows with a chevron that...A vertically stacked set of collapsible sections — hairline rows with a chevron that flips open→closed (WAI-ARIA Accordion pattern).

A WAI-ARIA breadcrumb trail — a nav landmark wrapping an ordered list of ancestor-page...A WAI-ARIA breadcrumb trail — a nav landmark wrapping an ordered list of ancestor-page links, ending with the current page.

A Breadcrumb trail that collapses its middle entries behind an overflow menu once the...A Breadcrumb trail that collapses its middle entries behind an overflow menu once the trail exceeds keepStart + keepEnd items.

A responsive, accessible carousel — a scroll-snap viewport of slides with prev/next...A responsive, accessible carousel — a scroll-snap viewport of slides with prev/next controls and indicator dots (WAI-ARIA Carousel pattern). Adapts to its container by default.

A single disclosure widget pairing a trigger with a panel that expands and collapses...A single disclosure widget pairing a trigger with a panel that expands and collapses — the single-item analogue of Accordion.

Page navigation for a paged collection — a row of square page cells with prev/next...Page navigation for a paged collection — a row of square page cells with prev/next chevrons, or a compact "Page X of Y" readout. Truncated ranges collapse behind an ellipsis that opens a menu of the hidden pages.

A step rail for a multi-step form — numbered markers joined by connectors, over the...A step rail for a multi-step form — numbered markers joined by connectors, over the headless Tabs. Each marker is a real tab: activation, aria-selected, the roving tabindex, Home/End and disabled all come from Tabs, restyled as a circle. orientation picks the rail direction; sized xs–xl, and data-density scales each size further.

An accessible tabbed interface — a tablist of triggers that switch between panels...An accessible tabbed interface — a tablist of triggers that switch between panels (WAI-ARIA Tabs pattern).

The desktop dropdown site nav — a transparent bar of top-level entries, each either a...The desktop dropdown site nav — a transparent bar of top-level entries, each either a plain link or a trigger that discloses a panel, with one panel open at a time. Panels project into a shared Viewport so the open one morphs into the next, and an Indicator (arrow or underline) tracks the open trigger. Implements the ARIA APG Disclosure Navigation Menu pattern, not a menubar: keyboard, hover-intent and focus are owned by the headless primitive.

A set of independent on/off buttons in a shared track — any number can be pressed...A set of independent on/off buttons in a shared track — any number can be pressed, including none. Framed like a Button: a pressed item is action/primary, an unpressed one action/secondary, inside a transparent bordered track whose radius is concentric with the items.

A user image with a graceful fallback for while it loads, or when it is missing or...A user image with a graceful fallback for while it loads, or when it is missing or broken.

An overlapping row of Avatars with an optional "+N" overflow counter — the...An overlapping row of Avatars with an optional "+N" overflow counter — the collaborators/attendees pattern. Composes the registry avatar component; the counter is itself an Avatar, not a Badge. Sized xs–xl; data-density scales each size further.

A small status/count indicator attached to another element or beside a heading.A small status/count indicator attached to another element or beside a heading. Read-only, never interactive. Four semantic tones × two treatments (a low-emphasis label chip, a high-emphasis counter chip), sized xs–xl; data-density scales each size further.

A content container — an optional media region plus a padded content block holding a...A content container — an optional media region plus a padded content block holding a header, description and footer. layout picks the arrangement: vertical (media above), horizontal (media beside), or cover (media behind the content, under a legibility scrim). Sized xs–xl; data-density scales each size further.

An interactive, removable label chip — filter bars, multi-select fields, inputs.An interactive, removable label chip — filter bars, multi-select fields, inputs. The trailing remove button is core to the anatomy, not optional; an optional leading icon or avatar may precede the label. Sized xs–xl; data-density scales each size further.

A framed data-table shell — a toolbar, a table and a footer that read as one object...A framed data-table shell — a toolbar, a table and a footer that read as one object, plus the anatomy sorting, selection and expandable rows need. Owns no state: sorting, selection, expansion, filtering and pagination all arrive as props, so an external table engine (TanStack Table) can drive it.

An accessible data table — a compound of standard HTML table elements (<table>...An accessible data table — a compound of standard HTML table elements (<table>, <thead>, <tbody>, <tr>, <th>, <td>, <caption>) with a tokenised default theme.

A small label chip that tags content by category, topic, or status — typically shown in...A small label chip that tags content by category, topic, or status — typically shown in a group. Read-only, never interactive. Five tones (a plain neutral treatment plus four semantic tones), sized xs–xl; data-density scales each size further.