# Rivier UI
> A component library for AI-native development: React components you copy into a project and own, themed
> from one place (light or dark, square to round, any highlight colour), covering controls, layout and bento
> grids, motion and transitions, 3D and charts, dates, flows, conversation, media. Built on Radix, Tailwind CSS,
> Motion and three.js. Keyboard operable, right-to-left safe, no fixed words: labels are props.
Install an item into a project: `rivier-ui add ` (it brings what the item depends on, and the theme).
Imports in a project: `@/components//` and `@/lib/cn`.
Rules for using and writing components: CONVENTIONS.md. Theming: registry/theme/rivier-ui.css.
## Helpers
### announce
Says a message to screen-reader users through one shared live region, politely or at once, without moving focus.
Use it: Something changed that a sighted person can see but no focus change will read out: an item was moved, a filter applied, a total changed, a reply finished. Not for content the person is about to read anyway, and not for errors on a field (use the field's own message). A component that is already a live region (status-line, toaster) does not need it.
```tsx
announce("Lunch moved to position 2 of 5");
announce("The connection was lost", "assertive");
```
### cn
Joins class names and resolves Tailwind conflicts, so a class passed in wins over a component's own.
Use it: Every component uses it. Use it wherever classes are combined conditionally.
```tsx
cn("px-4 py-2", isActive && "bg-primary", className)
```
### direction
Tells whether an element reads right to left, and turns "start" and "end" arrow keys and offsets the right way round for it.
Use it: A component handles Left and Right arrow keys, or moves something sideways with a transform, and must work in right-to-left pages. Layout itself needs no code: use logical utilities (ps-, ms-, start-, text-start). To set a direction for part of a page use direction-provider.
```tsx
function onKeyDown(event: KeyboardEvent) {
const step = inlineStep(event.key, event.currentTarget); // +1 towards the end, -1 towards the start, 0 otherwise
if (step !== 0) move(step);
}
```
### motion
The motion tokens as numbers for the motion package (easing, durations, a pointer spring), the useMotionSafe gate, and the entrance engine the reveal components share.
Use it: Any component animated with the motion package: take timing from here so it matches the CSS tokens, and gate on useMotionSafe so server markup is the final state. For CSS transitions use the duration-* and ease-out utilities instead.
```tsx
const safe = useMotionSafe();
return (
);
```
### theme-color
Resolves a theme CSS variable such as "--highlight" to an rgb() string that three.js and canvas code can parse, and re-reads it when the theme changes.
Use it: Anything that cannot use a Tailwind class or `var()`: three.js materials, canvas drawing. In markup use the token classes (`bg-primary`, `fill-chart-1`) instead.
```tsx
const { "--highlight": highlight, "--foreground": ink } = useThemeColors(["--highlight", "--foreground"]);
material.color.set(highlight);
// Outside React:
const border = readThemeColor("--border");
```
### use-controllable-state
State that a parent may control: it follows `value` when one is given and keeps its own from `defaultValue` when not, calling `onChange` either way.
Use it: Writing a component that should work both controlled (`value` + `onValueChange`) and uncontrolled (`defaultValue`), which every input-like component in the library does. Radix primitives already do this for their own state; use this for state the library adds on top.
```tsx
function Stepper({ value, defaultValue = 0, onValueChange }: { value?: number; defaultValue?: number; onValueChange?: (value: number) => void }) {
const [count, setCount] = useControllableState({ value, defaultValue, onChange: onValueChange });
return setCount(count + 1)}>{count} ;
}
```
### use-media
Follows an audio or video element (playing, time, duration, buffered, volume, rate, text tracks, waiting, error) as React state, with the actions to drive it, the context player parts share, and time formatting through Intl.
Use it: Building player parts around a `` or `` element the project renders. video-player, audio-player, captions and scene-strip are built on it; use it directly for a control they do not have. The element stays the source of truth: sources, HLS and DRM are attached to it by the project, and nothing here loads or decodes media.
```tsx
function Elapsed() {
const { state, locale } = useMediaContext("Elapsed");
return {formatMediaTime(state.time, locale)} ;
}
// Without a player around it
const [audio, setAudio] = useState(null);
const state = useMediaState(audio);
mediaActions(audio).toggle()}>{state.playing ? "Pause" : "Play"}
```
### use-size
Measures an element with ResizeObserver and returns its content width and height in whole pixels.
Use it: Drawing to the size of a container: charts, canvases. For layout that only needs to adapt, use container queries (`@container`, `@md:`) instead.
```tsx
const { ref, width, height } = useSize();
return {width > 0 && }
;
```
## Controls and surfaces
### accessible-icon
Gives an icon that stands alone a name for screen readers, and hides the drawing itself from them.
Use it: An icon that carries meaning with no words beside it and is not itself a control: a status mark in a table cell, a warning beside a figure. An icon-only button or link takes `aria-label` on the control instead; an icon beside its own words is decoration and takes `aria-hidden`.
```tsx
```
### accordion
Stacked sections whose content opens and closes under its heading.
Use it: Questions and answers, or long settings where people need a few sections out of many. `type="single"` keeps one open (add `collapsible` so it can be closed again); `type="multiple"` lets several be open. For views that replace each other in one place use tabs. Do not hide content everyone needs.
```tsx
How long does delivery take?
Two to four working days.
Can I send it back?
Yes, within thirty days.
```
### alert-dialog
A dialog that interrupts with a question and waits for an answer: it has no close button and does not close on a click outside.
Use it: Confirming something that cannot be undone (deleting, sending, leaving with unsaved work). Focus starts on AlertDialogCancel, so Enter never destroys by accident. For a task with fields, or anything that may simply be dismissed, use dialog; where the action can be taken back, do it at once and offer undo-line.
```tsx
Delete project
Delete this project?
Its files and history are removed for everyone. This cannot be undone.
Keep it
Delete
```
### alert
A message in the page with an icon, a title, a description and an optional action. Four variants: info, success, warning, destructive.
Use it: Telling the reader something about the page or the result of an action, in place. For a message that appears and leaves use a toast; for one that needs an answer use a dialog.
```tsx
Payment received
A receipt is on its way to your inbox.
The card was declined
Check the number and the expiry date, then try again.
Try again
```
### audio-player
The parts of a sound player around an `` element: play, a waveform that is also the time bar, time, speed and mute.
Use it: A voice note, a recording, a clip of music or narration a person plays and seeks in. The project gives the element its source and, for the waveform, the peaks (computed ahead of time, or with computePeaks for a short clip); without peaks the bar is a flat line of the same size. Offer a Transcript (from captions) for anything spoken. Nothing plays by itself. For video use video-player; for a plain time bar without a waveform use scrubber.
```tsx
// Peaks for a short clip, in the browser
const peaks = await computePeaks(await (await fetch("/note.mp3")).arrayBuffer(), 64);
```
### avatar
A round picture of a person or a team, with initials shown until the image loads or when it fails, and a group that overlaps.
Use it: Showing who something belongs to. Always give AvatarFallback initials; give AvatarImage an alt (the name), or alt="" when the name is printed next to it.
```tsx
HI
AK
BL
+3
```
### badge
A small label for a status, a count or a category. Six variants and an optional leading dot.
Use it: Marking a state or a tag next to other content. It is not clickable: for a removable or selectable chip use a button with size "sm".
```tsx
New
Beta
Live
Draft
```
### bottom-sheet
A panel that rises from the bottom edge, rests at one of several heights (snap points), and can be dragged between them or down to dismiss, with a keyboard handle that does the same.
Use it: Phones first: details, filters, a picker or a secondary task that should stay within reach of the thumb and may be peeked at before it is opened fully. With `modal={false}` it stays open while the page behind is used (a player, a route summary). For a panel from a side edge, or one with no snap points on a desktop, use sheet; for a short decision use dialog; beside the content on wide screens use dock. Always give it a BottomSheetTitle (add className="sr-only" to hide it). Opened by state with no BottomSheetTrigger, focus does not return on close: refocus the opener in `onCloseAutoFocus` on BottomSheetContent.
```tsx
Details
Saturday
Three things planned.
…
Done
// Controlled, in pixels and rems, staying open while the page is used
…
```
### breadcrumb
The path from the top of the site to the current page, as links with separators.
Use it: Pages nested three or more levels deep, above the page title. The last item is the current page: a BreadcrumbPage, not a link. For moving between sibling pages use tabs or the navbar. With a router link, pass it through `asChild`.
```tsx
Home
Projects
Atlas
```
### button
A button, or a link that looks like one. Five variants, three sizes, a loading state.
Use it: Any action. One "solid" per view for the main action; "outline" or "ghost" for the rest; "destructive" only for deleting.
```tsx
Save
Cancel
See pricing
Saving
```
### calendar
A month grid for choosing a day, several days or a range of days, with days that can be unavailable for a stated reason and days that carry a mark. Days are plain "YYYY-MM-DD" strings, so no time zone can move them.
Use it: Choosing dates where seeing the month matters: a booking, a stay, a deadline. It stays on the page; to open it from a field use date-picker. Never use the browser's native date input beside it. For a date far in the past that the person knows by heart (a birthday) three plain fields are quicker. Pass `locale` (the page's language) so that names, numerals and the first day of the week are right; without it the calendar is in English.
```tsx
// One day (uncontrolled), with days that cannot be chosen and days that carry a word
(closed.has(day) ? "nothing open" : false)}
marks={(day) => (busy.has(day) ? "busy" : undefined)}
/>
// A range (controlled), two months where there is room
const [stay, setStay] = useState({ start: null, end: null });
// Several days, and its own layout with a footer
A dot marks a busy day.
```
### captions
Captions drawn by the page instead of the browser, on a solid ground that reads on any picture, and a transcript: every line of a clip as a list that can be pressed to go there.
Use it: Inside video-player (Captions sits above the controls and moves with them) or beside audio-player (Transcript, or Captions with `inline`). Captions are for people who cannot hear the sound; a Transcript is also the alternative for people who cannot see or play it, so offer one for anything spoken. The lines come from a caption track of the media element (``), or from `cues` the project passes. Not a live region: with the sound on, a screen reader would talk over it.
```tsx
// In a video player: the lines of the element's caption track
…
// Beside an audio player: cues from the project, as a transcript
const cues = [{ start: 0, end: 4, text: "Welcome." }, { start: 4, end: 9, text: "This is the yard." }];
```
### card
A flat surface with a hairline edge, and parts for a header, title, description, content and footer.
Use it: Grouping related content: a plan, a stat, a form section. For a grid of unequal cards use bento-grid.
```tsx
Usage
This month
1,204 requests
Details
```
### carousel
A row of slides that is scrolled sideways one at a time (or a few at a time), with previous and next buttons, dots or a count, keys, and an optional autoplay that always has a pause button.
Use it: A handful of pictures or cards of equal weight where one (or a few) is enough at a time: the photos of a place, featured items, quotes. It is the browser's own scrolling with CSS scroll snap, so a swipe, a trackpad and momentum work as they do everywhere, right-to-left pages mirror by themselves and nothing moves under reduced motion; no carousel package is used (Embla, MIT, moves slides with transforms on its own engine, which this does not need). Set how many slides show with a basis on the slides (`className="basis-1/2 md:basis-1/3"`). Do not hide content a person must read in a carousel, and do not autoplay anything with text to read. For looking at pictures large use gallery with lightbox; for scenes of a clip use scene-strip; for thousands of items use virtual-list.
```tsx
{rooms.map((room) => (
))}
// Controlled, three to a view on wide screens, with a count; and one that plays by itself
{cards.map((card) => … )}
…
```
### certainty-legend
A small key of three or four named classes (how sure something is, or any other kind), each with its own pattern as well as its own colour, where each class can be switched off and on.
Use it: A scene, a map, a drawing or a chart marks its parts by class and the reader needs the key and a way to hide a class: what is recorded, what is worked out, what is a guess. The project supplies the names; the legend reports which classes are shown (`onValueChange`) and the project applies that to its own scene. Use CertaintySwatch to draw the same pattern in the scene's own key or in a caption. The pattern is what tells classes apart for someone who cannot tell the colours apart, so use it in the scene too. For filters with no key use chip; for the series of a chart, the chart's own legend.
```tsx
const classes = [
{ id: "recorded", label: "Recorded", description: "Measured on site" },
{ id: "inferred", label: "Inferred", description: "Worked out from what remains" },
{ id: "imagined", label: "Imagined", description: "A guess, drawn to complete the picture" },
];
scene.show(shown)} />
// The same pattern elsewhere
```
### checkbox
A checkbox with checked, unchecked and indeterminate states.
Use it: Choosing any number of options, or agreeing to something that is submitted with a form. For a setting that applies at once use switch; for exactly one of several use radio-group.
```tsx
Email me product news
```
### chip
A small pill for one short value: a filter that is on and can be removed, a suggestion to press, or one of a set of choices that can be switched on and off.
Use it: Filters in effect above a list (Chip with ChipRemove), suggested replies or refinements under a message or a search (ChipButton), and choosing one or several short options such as moods, tags or times of day (ChipGroup). For a status that cannot be pressed use badge; for two to five views of the same thing use segmented-control; for long labels use checkboxes or radio-group.
```tsx
// Filters in effect
Under 50
// Suggestions
ask("Only this weekend")}>Only this weekend
// A set of choices: several can be on (type="multiple") or one (type="single")
Calm
Lively
```
### collapsible
One section that a button opens and closes in place.
Use it: A single part of a page that is hidden until asked for: more options under a form, the rest of a long list, details under a summary. The trigger is yours to style (a Button through asChild). For several sections under headings use accordion; for content that floats over the page use popover.
```tsx
More options
Shown only while open.
```
### combobox
A select with a search field: a button that shows the choice and opens a list that narrows as one types.
Use it: Choosing one value from a list too long to scan: a country, a city, a person, a product. Under about eight options use select (or radio-group, or segmented-control for two to five); for running actions rather than choosing a value use command; for several values use chip or checkboxes. Name the trigger with a Label (`htmlFor` its `id`) or `aria-label`. Each item's `value` is what is stored; what is typed is matched against the item's text.
```tsx
const CITIES = [{ value: "lis", label: "Lisbon" }, { value: "opo", label: "Porto" }];
const [city, setCity] = useState("");
{CITIES.find((item) => item.value === city)?.label}
No city found.
{CITIES.map((item) => (
{item.label}
))}
```
### command
A command palette: a search field over a filtered, keyboard-driven list of actions, inline or in a dialog.
Use it: Fast access to many actions or pages by typing (the Ctrl/Cmd+K palette), or a searchable list inside a popover. For a handful of actions use dropdown-menu. CommandDialog is usually opened by a shortcut, with no trigger, so focus has nowhere to return: remember the opener (`opener.current = document.activeElement` before opening) and refocus it in `onCloseAutoFocus={(event) => { event.preventDefault(); opener.current?.focus(); }}`.
```tsx
const [open, setOpen] = useState(false);
setOpen(true)}>Search
Nothing found.
setOpen(false)}>Dashboard
setOpen(false)}>Settings Ctrl ,
setOpen(false)}>Sign out
```
### compare-slider
Two layers of the same size, one over the other, with a divider that is dragged or moved with the keyboard to show more of one and less of the other: then and now, before and after.
Use it: Comparing two views of the same thing in the same frame: two pictures, two maps, two 3D viewers, any two children. Each side has a visible name. The divider is a slider, so it works without dragging. The frame is drawn left to right in every language (a picture is not mirrored in a right-to-left page), so the first layer is always on the left and the arrow keys move the divider the way they point. For two things that are not the same view use two cards side by side; for many pictures use gallery or carousel.
```tsx
// Controlled, with any two children
```
### compare-table
Two to four things side by side, attribute by attribute: a table whose first column (the attribute names) stays in view while the things scroll sideways inside it on narrow screens.
Use it: Helping someone choose between a few similar things: plans, products, places, quotes. Give every thing the same rows, in the same order. For plain rows of data use table; for more than four things let people pick which to compare first; for one thing's details use a description list or card.
```tsx
Starter Choose
Team Choose
€12
€29
By email
By email
```
### composer
The box a person writes a message in: a field that grows with the text, a list of attachments, and a toolbar with slots for an attach button, a voice button and send (which becomes stop while a reply is on its way).
Use it: Under a thread, or anywhere a person sends free text to an assistant or to other people. It owns the text and the keys (Enter sends, Shift+Enter makes a new line, nothing is sent while an input method is composing); the project owns the files, the microphone and the sending. For one line with no attachments (a search box) use input-group; for a long form field use textarea.
```tsx
{files.map((file) => (
remove(file)} removeLabel={`Remove ${file.name}`}>{file.name}
))}
```
### consent
Asks permission before something is switched on or shared: what is asked for, item by item, each optional one with its own switch that starts off, and two equal buttons to allow or decline. As a sheet (ConsentSheet) or in the page (ConsentPanel).
Use it: Before sharing a person's data with another party, connecting an account, turning on an assistant or a feature that reads their content, or using a device permission. One consent per purpose, in plain words, at the moment it is needed. Nothing is pre-ticked and declining is as easy as allowing. For a yes or no about an action the person just started (delete, leave) use dialog; for a cookie notice use the same parts in a ConsentPanel.
```tsx
connect(granted)} onDecline={skip} onDismiss={skip}>
Connect calendar
Let the planner see your calendar?
It is used to avoid times when you are busy. You can stop this in Settings at any time.
Kept for 30 days, never sold, deleted when you disconnect.
Do not allow
Allow
```
### context-menu
A menu of actions that opens at the pointer on right-click, and on a long press on touch screens: items, checkbox and radio items, labels, separators, sub-menus and a shortcut slot.
Use it: Shortcuts to actions on a thing in a dense interface (a file, a row, a canvas object). Nothing shows that it exists, so every action in it must also be reachable another way; for a visible button use dropdown-menu.
```tsx
Right-click, or press and hold
Open Enter
Pinned
Label
None
Urgent
Delete
```
### countdown
The time left until a moment, as text that counts down ("4 min 12 s"), announced to screen-reader users only at the moments the project lists.
Use it: Something the person holds for a limited time: a reserved seat, a price that is kept, a code that expires, a session about to end. Say what happens at the end and offer a way to get more time beside it. Not for decoration or pressure: a countdown that restarts or means nothing is a dark pattern. For progress through a known amount of work use progress.
```tsx
Your seats are held for{" "}
`${left} left to finish booking`}
onExpire={release}
expiredLabel="no longer: the hold has ended"
/>
```
### date-picker
A button that shows a date, or a range of dates, and opens a calendar in a popover to choose it. Values are "YYYY-MM-DD" strings.
Use it: A date or a stay inside a form or a toolbar, where a calendar that is always open would take too much room. When the calendar is the main thing on the screen use calendar itself. Never the browser's native date input. Name the button by passing `aria-labelledby` with the id of its visible label: the chosen date is added to the name.
```tsx
// One day, uncontrolled, submitted with a form as "date"
Date
(closed.has(day) ? "nothing open" : false)} />
// A range, controlled, two months where there is room
const [stay, setStay] = useState({ start: null, end: null });
```
### dialog
A modal window over a dimmed page, with parts for a header, title, description and footer.
Use it: A short task or a decision that must be finished or dismissed before going on. For a panel from an edge (menus, filters, details) use sheet; for something small attached to a control use popover. Always give it a DialogTitle (add className="sr-only" to hide it). Opened by a DialogTrigger, focus returns to that trigger on close. Opened by state with no trigger (a shortcut, a menu item), Radix has nothing to return to: remember the opener (`opener.current = document.activeElement` before opening) and refocus it in `onCloseAutoFocus={(event) => { event.preventDefault(); opener.current?.focus(); }}` on DialogContent.
```tsx
Rename
Rename project
The address of the project does not change.
Cancel
Save
```
### direction-provider
Sets the reading direction (left to right, or right to left) for everything inside it: the `dir` attribute for layout and text, and the context Radix-based components read for arrow keys and placement.
Use it: Once around the app, with the direction of the current language, in any product that has or may get a right-to-left language (Arabic, Hebrew, Persian, Urdu, Dhivehi). Also around one part of a page in the other direction. A product in one left-to-right language does not need it. Put `dir` on as well (the provider's own element covers only what is inside it; menus and dialogs are portalled to ). For people's own words in an unknown language use `dir="auto"` on that element instead.
```tsx
// app/layout.tsx
const dir = directionOf(locale); // "rtl" for "ar", "he", "fa", "ur", "dv" …
{children}
// anywhere below
const dir = useDirection();
```
### dock
A layout of main content with a panel docked beside it that stays while the person works: the panel can be resized with a splitter, collapsed to a slim bar, and on narrow containers gives way to a bar at the bottom.
Use it: A working surface that belongs beside the content and is not modal: a plan next to a conversation, an inspector next to a canvas, details next to a list. For a panel that covers the page for a moment use sheet; for two fixed columns with no resizing use split. Write the parts in reading order: DockMain, DockResizer, DockPanel for a panel at the end; DockPanel, DockResizer, DockMain with side="start". Below 42rem of its own width (another width with `stackBelow`) the panel and splitter are hidden and DockBar shows at the bottom: open the panel's content in a bottom-sheet from `onOpenStacked`. Where the content ends in a region that must stay lowest (a composer), put a second DockBar inside DockMain above that region with `show="stacked"`, and give the one after the panel `show="collapsed"`. Give the Dock a height (it fills its parent).
```tsx
…the conversation…
…the plan…
setSheetOpen(true)}>Plan · 3 stops
// Controlled, in pixels, at the start
…
// Stacks below 56rem; on a narrow dock the bar sits above the composer, not under it
…the conversation…
setSheetOpen(true)}>Plan · 3 stops
…
Plan · 3 stops
```
### dropdown-menu
A menu of actions that opens from a button: items, checkbox and radio items, labels, separators, sub-menus and a shortcut slot.
Use it: A list of actions or options behind one button (an account menu, "more" on a row). For choosing one value in a form use select; for actions on right-click use context-menu; for free content use popover. An icon-only trigger needs an `aria-label`.
```tsx
Options
Project
Rename F2
Show in sidebar
Move to
Work
Archive
Delete
```
### dropzone
A place to choose files to upload, by dropping them, pasting them or pressing a button, and the rows that show each file's progress with slots for pause, resume, retry and remove.
Use it: Adding pictures, documents or other files where progress matters: a listing's photos, attachments, an import. It contains no upload engine: the project uploads (plain, or resumable such as tus) and tells each row its state and progress. For one small file in a form, an input with type="file" is enough. Name the dropzone with `aria-label` or `aria-labelledby`, and word rejected files yourself from the reason given to `onReject`.
```tsx
Drop pictures here, or
Choose pictures
{uploads.map((upload) => (
{upload.state === "uploading" ? pause(upload.id)} /> : null}
{upload.state === "paused" ? resume(upload.id)} /> : null}
{upload.state === "failed" ? retry(upload.id)} /> : null}
remove(upload.id)} />
))}
// A state of the project's own, with its word and tone; and a row that is not a list item
```
### empty-state
What a list, a table or a search shows when there is nothing in it: an icon, a title, a description and an action.
Use it: An empty list, zero search results, a first run. Say what belongs here and offer the one action that fills it. For a failure use alert; while loading use skeleton.
```tsx
New project}
/>
} title="No results" description="Try a shorter search." bordered={false} />
```
### fact-row
One thing the system knows or remembers about a person or a record, shown with where it came from and what the person can do about it: correct it in place, say it is no longer true, or have it removed.
Use it: Showing people what is held about them and letting them control it: remembered preferences, profile details filled in by an assistant, imported data, settings inferred from use. Every fact gets a source and at least one action. The words of the actions are the project's (the component names none). For plain label and value pairs nobody can change use a description list; for a form use field.
```tsx
Diet
{diet}
}>You said this on 3 May
Edit
Not true any more
setForgotten(true)}>Forget this
Diet was forgotten. setForgotten(false)}>Undo
```
### field
Lays out a label, a control, a description and an error message, and connects them (htmlFor, id, aria-describedby, aria-invalid) without hand-written ids.
Use it: Every control in a form. Put the control inside FieldControl; render FieldError only when there is a message and the field turns invalid by itself. Use orientation="horizontal" for a checkbox or switch beside its label, and FieldControl group for a radio group, toggle group or slider.
```tsx
Email
We only use it to reply.
{error}
Weekly summary
Plan
Free
Pro
```
### gallery
A set of picture tiles that open a full-screen viewer: a mosaic of one large and several small, an even grid, or a row that scrolls sideways.
Use it: Showing several pictures of one thing where each can be looked at closely: a place, a product, a piece of work. GalleryLightbox takes a list of pictures and does everything; Gallery, GalleryItem and GalleryImage are the parts, to put inside your own Lightbox or to use with no viewer at all. Pictures are plain ` ` elements unless the project gives its framework's image component: `as` on GalleryImage, `renderImage` on GalleryLightbox. For pictures that are decoration, use plain images in a grid; for one picture use aspect.
```tsx
// The parts, in your own lightbox
{photos.map((photo, index) => (
))}
…
// With the framework's image component (here next/image) in place of
use === "tile" ? :
}
/>
```
### hotspots
Named buttons placed over a picture or a video at a point, each present only between two moments of the clip, with the same choices as a plain list for people who cannot point at the picture.
Use it: Something in the frame can be asked about or chosen while it is on screen: an object in a scene, a place on a still, a choice in a story. Put Hotspots inside the frame (VideoPlayer, or any `relative` box over a picture) and HotspotList after it; both take the same `hotspots`. A hotspot that appears is announced, because nothing else would tell a screen-reader user it is there. For a point on a map use the map's own markers; for marks on the time bar use the scrubber's `marks`.
```tsx
const spots = [
{ id: "kiln", x: 32, y: 55, start: 4, end: 12, label: "The kiln door" },
{ id: "shelf", x: 70, y: 30, start: 9, end: 20, label: "Drying shelf" },
];
openCard(spot.id)} />
…
openCard(spot.id)} aria-label="In this scene" />
```
### hover-card
A preview that appears beside a link while the pointer rests on it or the keyboard focuses it.
Use it: A look ahead at where a link goes: a person, a page, a record. It does not open on touch and a screen reader does not announce it, so it only ever repeats what following the link shows. For a hint of a few words use tooltip; for anything a person must be able to reach or act on use popover.
```tsx
Ada Lovelace
Ada Lovelace
Wrote the first published program.
```
### input-group
An input with a leading or trailing icon, text or button inside one shared border.
Use it: A search box with an icon, a URL with a fixed prefix, a field with a unit or an inline action. For a plain input use input. Inside a field, wrap InputGroupInput (not the group) in FieldControl.
```tsx
https://
Check
```
### input
A single-line text input in three sizes, with an invalid state.
Use it: Short free text: a name, an email, a number. Wrap it in field for a label and an error; use textarea for several lines, select for a fixed list, input-group to add an icon or a button inside the edge.
```tsx
```
### kbd
A key cap for showing a keyboard key or a shortcut.
Use it: Naming a key the reader can press: in a menu item, a tooltip, a hint under a field. Wrap a combination in KbdGroup, one Kbd per key.
```tsx
Esc
Ctrl
K
```
### label
The text name of a control. Clicking it focuses or toggles the control it points to.
Use it: Every control needs one. Point it at a control with htmlFor, or wrap a checkbox, radio or switch in it so the whole row is the hit area. Inside field, use FieldLabel, which wires htmlFor for you.
```tsx
Email
Remember me
```
### language-switcher
A menu for choosing the interface language: each language under its own name in its own script, the current one marked, no flags.
Use it: A product in more than one language: in the header or footer, and in settings. It only reports the choice (`onValueChange`): the project navigates to the translated page or stores the preference. A flag stands for a country, not a language, so none is shown. It is a menu of radio items and not a select, because choosing a language is an action that reloads or navigates: a select that changes the page as its value changes surprises keyboard and screen-reader users. For choosing a language as data in a form (a document's language) use select.
```tsx
router.replace(pathname, { locale: next })} label="Language" languages={["en", "fr", "ar", "ja"]} />
// With its own parts: names in the current language as a second line, and a name the project supplies
```
### lightbox
A full-screen viewer for a set of pictures (or any media the project renders): swipe or arrow between slides, zoom and pan, a counter, captions, thumbnails, and the picture growing out of the thumbnail that opened it.
Use it: Looking closely at pictures that are shown small on the page: a listing's photos, a portfolio, attachments. It is a modal dialog, so focus is held inside and returns to the thumbnail of the picture shown when it closes. For a grid of thumbnails that opens it use gallery (GalleryLightbox does both). For one picture with text beside it use dialog; for a row of cards that scroll in the page use a scroll-snap row, not a lightbox. Always give it a LightboxTitle (className="sr-only" hides it) and say how many slides there are with `count`.
```tsx
{photos.map((photo, index) => (
))}
Photos
{photos.map((photo, index) => (
))}
```
### media-row-list
The pictures or clips a person has added, as rows they can put in order, describe and choose a cover from: each row shows its state in words (an upload's, or one the project names), its progress or its error with pause, resume and retry, a field for its text alternative that can be required, a "cover" choice, a remove button, and room for a status line and controls of the project's own.
Use it: After a dropzone, when the order of the files matters and each needs a description: the photos of a listing, the slides of a story, the pages of a document. It is ready-made from sortable-list (drag by the handle, lift and move with the keyboard, or the move buttons; every move is read out) and the upload rows of dropzone, and contains no upload engine: the project uploads and passes each row its state. For files whose order does not matter use the dropzone's own UploadList; to reorder things that are not files use sortable-list.
```tsx
const [rows, setRows] = useState([
{ id: "a", name: "kitchen.jpg", size: 1_200_000, state: "done", alt: "The kitchen, from the door" },
{ id: "b", name: "garden.jpg", size: 2_400_000, state: "uploading", progress: 40 },
{ id: "c", name: "stairs.jpg", state: "failed", error: "The connection dropped." },
]);
const [cover, setCover] = useState("a");
setRows((all) => all.map((row) => (row.id === id ? { ...row, alt } : row)))}
onRemove={(id) => setRows((all) => all.filter((row) => row.id !== id))}
onRetry={(id) => upload(id)}
/>
// A state of the project's own, a status line, a control of its own, no cover choice, and a description that is required
const row: MediaRow = {
id: "d", name: "walk.mp4", state: "checking", stateLabel: "Being checked", stateTone: "warning",
status: "Usually takes a minute.", controls: Trim ,
hideCover: true, altRequired: true, altError: "Say what the clip shows.",
};
save(values)} />
```
### menubar
A row of menus that stays on screen, as along the top of a desktop application: File, Edit, View.
Use it: A working tool (an editor, a canvas, a table) with many commands that belong in named groups. The arrow keys move between the menus and through each one. Give the bar an `aria-label`. For one menu behind one button use dropdown-menu; for links between the pages of a site use navigation-menu or navbar.
```tsx
File
New Ctrl N
Print
View
Ruler
```
### message
One message in a conversation, from the person, the assistant or the system, with parts for an avatar, the words, the time and sending state, a toolbar of actions, and suggested replies.
Use it: Inside a thread, one per message. The person's own messages sit at the end side in a bubble; the assistant's read as plain text at the start. For words that are still arriving put streaming-text inside MessageContent; for a structured piece of a reply (a plan, a form) use part-frame beside it. Not for comments under an article or a notification list: those are plain lists.
```tsx
Somewhere quiet for lunch on Saturday?
AI
Three places are open then.
send("Only outdoors")}>Only outdoors
```
### navbar
A responsive site header: a brand, a row of links and a slot for actions. Below `md` the links move into a menu button that opens them in a sheet.
Use it: The top of a site or app with up to about seven top-level links. The links are written once, as NavbarLink children, and shown in the bar or in the sheet. The sheet closes when a link in it is followed, and focus returns to the menu button. Mark the current page with `current`. With a router link, pass it through `asChild`. For navigation inside a page use tabs; for the path to a page use breadcrumb.
```tsx
Rivier}
actions={Contact }
>
Work
Studio
About
```
### navigation-menu
A row of site links where some open a panel of further links beneath them.
Use it: The main navigation of a site whose sections each have pages worth showing: products, documentation, a catalogue. A plain link is a NavigationMenuLink in an item; a section is a NavigationMenuTrigger with a NavigationMenuContent. Mark the current page with `active`. For a header with a brand, links and a phone menu use navbar; for commands rather than places use menubar or dropdown-menu.
```tsx
Guides
Getting started
Theming
Pricing
```
### number-stepper
A number with a button either side to take one away or add one, that can also be typed: a spin button.
Use it: A small whole number that is usually changed by a step or two: people in a party, a quantity, nights. For a number where the rough position matters use slider; for a free number (a price, a year) use input with type="number". Name it with a Label (pass the same `id`) or `aria-label`.
```tsx
Adults
// Controlled, with its own parts and translated button names
```
### otp-field
A one-time code typed into one box per character: typing moves on, Backspace moves back, and a pasted code fills every box.
Use it: A short code sent by message or read from an authenticator. It posts as one value under `name`, and the browser can offer the code it has just received. Label it with `aria-label`, or put it in a field with FieldControl group. For a password use password-field; for any other short text use input.
```tsx
```
### pagination
Links to the previous, next and numbered pages of a long list, with the look of buttons.
Use it: A list or table split over pages that people may want to jump within or link to. Each page is a real link, so it works without JavaScript; with a router link, pass it through `asChild`. On the first or last page give PaginationPrevious or PaginationNext `aria-disabled="true"` and no `href`. For a feed with no natural page numbers use a "Load more" button.
```tsx
1
2
9
```
### part-frame
A card for one structured piece of a conversation (a plan, a result, a form) that has a life: loading, live, saving a change, replaced by a newer one, or final.
Use it: An assistant's reply contains something to look at or work in, not only words, and that thing changes over the conversation. The frame holds its size while it loads, says "Saving" in words while a change is on its way, shrinks to a one-line stub when a newer frame replaces it, and can open its content full screen. For a static card use card; for words use message; for a flow of steps put steps or a wizard inside it.
```tsx
Plan for Saturday
Confirm
// Replaced by a newer one: a stub that says so and points to it
See the new plan}>
Plan for Saturday
…
```
### password-field
A password input with a button that shows or hides what was typed.
Use it: Every place a password is typed. The value is hidden again when the form is sent, and the button keeps the caret where it was. Set `autoComplete` to "current-password" (signing in) or "new-password" (choosing one) so a password manager knows which to offer. For a code sent by message use otp-field.
```tsx
Password
```
### popover
A small floating surface attached to the control that opens it.
Use it: Extra controls or details that belong to one control: a date picker, a share box, quick settings. For a hint of a few words use tooltip; for a list of actions use dropdown-menu; for a task that must block the page use dialog.
```tsx
Share
Share this page
Anyone with the link can view it.
```
### price-breakdown
What a price is made of, line by line, and the total: labels at the start, amounts in aligned figures at the end.
Use it: A quote, a basket summary, a receipt, a booking's cost before paying. Every amount the total includes gets a line, discounts and fees too. For one figure with a label use stat; for many records in rows and columns use table.
```tsx
`Total is now ${total}`}>
```
### progress
A bar that fills as a task completes, or slides back and forth when the amount done is not known.
Use it: A wait that can be measured: an upload, a multi-step job. Leave `value` out (or pass null) for the indeterminate state. For a short unknown wait use spinner. Always label it.
```tsx
```
### provenance-label
A label that stays on a picture, a video or a 3D view and says what it is (a photograph, a reconstruction, made by a model), with a popover for its sources, placed so the media's own controls can never cover it.
Use it: A reader must not mistake what they are looking at: a reconstruction beside a photograph, a generated picture, an artist's impression, archive footage. Two placements. ProvenanceFrame puts the label in its own strip above the media, outside the media's box, where nothing the media draws can reach it: use this by default. `position` puts it over a top corner inside the media's box, above its controls and on a solid ground: use this when the label must also stay in full screen, with the label inside the element that goes full screen. The bottom edge is left to controls and captions. For the source of one fact in text use fact-row's SourceChip; for a key of classes inside a scene use certainty-legend.
```tsx
// In its own strip above the media
Drawn from the 1890 survey and two photographs. The roof is a guess.
}>Imagined reconstruction
// Over a corner of a player, so it stays in full screen
Imagined reconstruction
…
```
### radio-group
A set of radio buttons where exactly one is chosen, with arrow-key movement between them.
Use it: Picking one of two to five options that should all be visible. For a longer list use select; for a compact row of icons or short words use toggle-group; for on or off use switch.
```tsx
Monthly
Yearly
```
### scene-strip
A row of the scenes or chapters of a clip, each with a picture, a name and a length, that scrolls sideways, marks the one that is playing and goes to a scene when it is pressed.
Use it: Under or beside a player whose clip has named parts: chapters of a lesson, scenes of a film, steps of a recipe. It reads the time from the player it is inside (wrap the player and the strip in VideoPlayerProvider, or put it inside AudioPlayer), or from `time` and `onSeek`. For marks on the time bar itself use the scrubber's `marks`; for the spoken lines use Transcript.
```tsx
…
},
{ start: 42, label: "On the wheel", picture: },
]}
/>
```
### scroll-area
A scrolling region with thin, themed scrollbars that look the same on every platform. Native scrolling underneath.
Use it: A bounded list or panel inside a surface: a menu, a sidebar, a log. Give it a height (or a max height). The page itself, and anything that can simply grow, should scroll natively.
```tsx
Long content…
…
```
### scrubber
The time bar of a player: a slider over the length of a clip that shows what has played and what has loaded, marks chapters, and can show the time and a picture for the moment under the pointer.
Use it: Seeking in audio, video or any timeline measured in seconds. video-player and audio-player already contain one bound to their media; use this directly for a custom player or a timeline. For choosing a number that is not a time use slider. Time runs left to right in every language (as on players everywhere: the bar is a picture of time, like a clock face, not a line of text), so the bar and its arrow keys are not mirrored in right-to-left pages; pass `dir="rtl"` if a product decides otherwise, and the keys follow what is drawn.
```tsx
// Uncontrolled
player.seek(time)} />
// Controlled by the player's clock, with chapters and a preview picture from a sprite sheet
```
### segmented-control
A row of two to five segments where exactly one is chosen, with a marker that slides to the choice.
Use it: Switching one setting between a few short, equal options that take effect at once: a view (list or map), a unit, a period (day, week, month). It is a radio group, so one option is always chosen. For switching panels of content use tabs; for options that can each be on or off use toggle-group or chip; for more than five options use select.
```tsx
List
Map
// Controlled, full width, with icons
Day
Week
```
### select
A themed dropdown for choosing one value from a list, with groups, labels and separators. Never a native select.
Use it: Picking one of more than about five options, or when space is tight. For two to five visible options use radio-group; for a short row of icons use toggle-group.
```tsx
Europe
Euro
Swedish krona
Americas
US dollar
Canadian dollar
```
### separator
A hairline between two pieces of content, horizontal or vertical, with an optional label in the middle.
Use it: Dividing groups inside a surface or a toolbar. Between page sections use section spacing instead, and inside a list prefer a border on the rows.
```tsx
or continue with
Docs
Blog
```
### sheet
A modal panel that slides in from an edge of the screen, with parts for a header, title, description and footer.
Use it: Navigation, filters, details or a longer form beside the page. `side` is "end" by default ("start" and "end" follow the reading direction; "left" and "right" do not); on phones "bottom" is the natural choice, because it is within reach of the thumb. For a short decision in the middle of the screen use dialog. Always give it a SheetTitle (add className="sr-only" to hide it). Opened by state with no SheetTrigger, focus does not return on close: remember the opener (`opener.current = document.activeElement`) and refocus it in `onCloseAutoFocus={(event) => { event.preventDefault(); opener.current?.focus(); }}` on SheetContent.
```tsx
Filters
Filters
Narrow the list of projects.
…
Show results
```
### skeleton
A pulsing block that stands in for content that is loading: a bare block sized by hand, lines of text, or a wrapper that takes the exact size of the real content. It is still under reduced motion.
Use it: Content whose shape is known is on its way. Nothing may jump when it arrives: either size the block like the thing it replaces, or wrap the real component (rendered with placeholder data) in `` so the box is exactly its final size. Mark the region that is loading with `aria-busy="true"`: the placeholders themselves are hidden from assistive technology. For an unknown wait use spinner; for a measurable one use progress.
```tsx
// Holds the final size: the card is laid out, invisible and inert, under the placeholder
```
### slider
A slider for one value, or a range with two thumbs.
Use it: Choosing a number where the rough position matters more than the exact figure: volume, a price range. When the exact number matters use an input with type="number".
```tsx
```
### slot-picker
Offered times as a set of pills to choose one from, optionally under named groups, each able to carry a note and to be unavailable for a stated reason.
Use it: The times are a short list that someone else decides: appointment slots, sittings, departures. One is chosen, so it is a radio group. For any time of the person's own choosing use time-picker; for more than about twenty slots, narrow them first (by day, by part of the day) or use select.
```tsx
// Controlled, with its own labels, and nothing on offer
{sittings.length === 0 ? Nothing is open on this day. : null}
{sittings.map((sitting) => {sitting.name} )}
```
### sortable-list
A list whose order the person sets, three ways: dragging a row by its handle (mouse, pen or touch), lifting it with the keyboard and moving it with the arrow keys, or pressing "Move up" and "Move down" buttons. Every move is read out.
Use it: The order itself is the data: the stops of a plan, priorities, pictures in a gallery, columns to show. Always give the rows SortableMoveButtons or a SortableHandle (both is best): dragging alone leaves out people who cannot drag (WCAG 2.5.7). It is one vertical list; it does not move rows between lists or sort a grid. For a list sorted by a rule (newest first) use a select for the rule instead; for choosing rather than ordering use chip or checkboxes.
```tsx
const [stops, setStops] = useState(["market", "lunch", "museum"]);
{stops.map((id) => (
{NAMES[id]}
))}
// Uncontrolled: the list keeps the order and gives it to its children
{(order) => order.map((id) => … )}
// Save once, when a row has been let go, not at every step it passes
(from === to ? undefined : save(values))} aria-label="Stops, in order">…
```
### spinner
A turning ring that says something is in progress, announced to assistive technology by its label.
Use it: A short wait of unknown length. Inside a button use the button's `loading` prop; when the shape of the content is known use skeleton; when the amount done is known use progress.
```tsx
Saving
```
### stat
A number tile: a label, a value, an optional change with its direction, and a slot for a sparkline.
Use it: A headline figure on a dashboard or in a bento cell. Pass `change` as a magnitude ("12%"): the sign and the arrow are added from `direction`. For several figures compared over time use a chart or a table.
```tsx
}
/>
```
### status-line
One line that says in words what is happening now ("Searching", "Writing a reply", "Done"), read out politely by screen readers, with an optional moving mark and a slot for a stop button.
Use it: Beside a thread or any surface where work goes on that the person waits for: it is the one polite live region of that surface. Render it from the start, empty, and change its text: a region that appears together with its text is often not announced. It keeps its height when empty, so nothing jumps. For a wait with no words use spinner; for a measurable one use progress; for a result that must outlive the moment use alert or toaster.
```tsx
Stop : null}>
{busy ? "Searching three sources" : ""}
```
### steps
A rail that shows where one is in a sequence of steps: a row of thin segments, or numbered markers with titles, each step with a state (done, filled in for you, current, not started, skipped, blocked).
Use it: Showing progress through a known, ordered set of steps: a booking, a sign-up, an import, a checklist that runs in order. Use "segments" above a card where space is short and "labelled" where the step names help. Pair it with StepsCount ("Step 2 of 5"), which says the same in words. For a measured amount of one task use progress; for the whole guided task with its buttons use wizard, which draws this rail itself; for moving between unordered views use tabs.
```tsx
Dates
People
Extras
Review
// Numbered markers with titles; a finished step can be a button that goes back to it
goTo("file")}>Choose a file
Match the columns
Check the rows
Add notes
```
### streaming-text
Text that grows as it arrives, with a caret while it is arriving, that is never read out word by word: it is announced once, when it is finished.
Use it: A reply from a model, a transcript or a log line that streams in. Pass the text so far and whether more is coming. It must not sit inside a live region (a thread is `aria-live="off"`); say "Writing a reply" through a status-line while it streams. For text that is already complete use a plain element; for a headline that animates in use text-reveal.
```tsx
// A shorter spoken form, and words that fade in as they land
// The project's own renderer (Markdown, for example)
{(text) => {text} }
```
### switch
An on/off switch.
Use it: A setting that takes effect as soon as it is flipped. For a choice that is submitted with a form use checkbox; for a pressed/unpressed toolbar button use toggle.
```tsx
Weekly summary
```
### table
A semantic table with styled parts, inside a wrapper that scrolls sideways so it never overflows a narrow screen.
Use it: Rows of the same kind of thing compared across columns. For sorting, filtering and paging build on these parts. For two or three facts per item use cards; for one number use stat.
```tsx
Invoices this quarter
Invoice
Status
Amount
INV-001
Paid
€250.00
Total
€250.00
```
### tabs
Panels that share one place, switched by a row of tabs. Two looks: an underline, or a segmented pill.
Use it: Views of the same thing that people switch between without leaving the page. `variant="underline"` (the default) for sections of a page; `variant="pill"` for a compact switch between two to four views. For moving between pages use links (navbar, breadcrumb); for stacked sections that can be open together use accordion.
```tsx
Overview
Activity
The overview.
The activity.
Monthly
Yearly
Billed every month.
Billed once a year.
```
### textarea
A multi-line text input that grows with its content, with an invalid state.
Use it: Free text of more than one line: a message, a note, a description. Wrap it in field for a label and an error; use input for a single line.
```tsx
```
### theme-provider
Holds the theme (light or dark, roundness, highlight colour), applies it to the page, remembers the visitor's choice, and avoids a flash of the wrong theme.
Use it: Once, around the app in the root layout, when visitors or the product can change the theme. For a fixed theme, skip it and set the attributes on by hand.
```tsx
// app/layout.tsx
{children}
// anywhere below
const { theme, setTheme } = useTheme();
setTheme({ mode: "dark" });
setTheme({ accent: { hue: 262, chroma: 0.19 } });
```
### thread
The scrolling log of a conversation: it follows the newest content while the person is at the bottom, stops the moment they scroll up, and offers a way back down.
Use it: A conversation with an assistant or between people, where messages arrive over time. It holds no messages and no transport: render them inside it (message, streaming-text, part-frame). The log is deliberately silent (`aria-live="off"`): say what is happening through one status-line beside it, and the finished reply once through streaming-text's `announceWhenDone`. For a list that does not grow at the bottom use scroll-area.
```tsx
{messages.length === 0 ? Ask anything to begin. : null}
{messages.map((message) => (
{message.text}
))}
Jump to latest
// Always show what the person just sent, even if they had scrolled up
…
```
### tile-group
A grid of large tiles, each a picture or an icon with a word, where one or several are chosen.
Use it: A choice that is easier to make by looking than by reading: moods, styles, room types, plans. Each tile must carry a visible word; the picture alone is never the label. For short text-only options use chip (ChipGroup); for a compact switch between a few views use segmented-control; for a long list use select or combobox.
```tsx
Quiet
Gardens, reading rooms, slow walks
Lively
```
### time-picker
A time field made of an hour and a minute that are each stepped with the arrow keys or typed, with an AM/PM part where the locale uses a 12-hour clock. The value is a 24-hour "HH:mm" string.
Use it: Any time of the person's own choosing: an opening hour, a reminder, an arrival. When the times on offer are a fixed list use slot-picker. Never the browser's native time input. Name it with `aria-label` or `aria-labelledby`.
```tsx
Opens at
// Controlled, limited, 12-hour whatever the locale, with translated names
```
### timeline
An ordered list of numbered rows joined by a line: each with an optional time, a title and content, and a state (done, current, upcoming).
Use it: Things that happen in an order: the parts of a day, the stages of an order or a delivery, a history of changes, the steps of a plan. The number and the state are read out with each row. For the steps of a form the person is filling in use steps; for rows people reorder use sortable-list; for unordered items use a plain list.
```tsx
09:30
Market walk
Meet at the north gate.
12:30
Lunch
Free afternoon
```
### toaster
The place where toasts appear: sonner's Toaster drawn with the theme's tokens, and its `toast` function.
Use it: Short confirmations and errors that need no decision ("Saved", "Could not connect"). Render one Toaster in the root layout, then call `toast` from anywhere on the client. For something that must be answered use dialog; for a message that belongs to a field or a section, show it there.
```tsx
// app/layout.tsx
{children}
// any client component
toast.success("Saved", { description: "Your changes are live." })}>Save
```
### toggle-group
A joined row of toggles where one (type="single") or several (type="multiple") are on.
Use it: A compact choice between a few short options or icons: alignment, a view switcher, text styles. For options with longer labels use radio-group (one) or checkboxes (several); for switching panels use tabs.
```tsx
Grid
List
```
### toggle
A button that stays pressed: on or off.
Use it: A toolbar state such as bold, mute or pin. For a setting use switch; for several toggles that belong together, or a pick-one row, use toggle-group.
```tsx
Pinned
```
### toolbar
A row of buttons, toggles and links that the keyboard enters once and then moves through with the arrow keys.
Use it: The controls over an editor, a canvas, a table or a player: one Tab stop for the whole row, however many controls it holds. Give it an `aria-label`. For one group of toggles on its own use toggle-group; for commands in named menus use menubar.
```tsx
Help
Save
```
### tooltip
A few words that appear beside a control on hover or keyboard focus.
Use it: Naming an icon-only button or adding a short hint. It does not open on touch, so never put anything needed there: the control keeps its own `aria-label`. For content people interact with use popover. Put one TooltipProvider around the app (root layout); every Tooltip must be inside one.
```tsx
Copy link
```
### undo-line
A line that stays where something was just done, says what it was, and offers to undo it.
Use it: After an action that can be taken back, inside the place it happened: a row removed from a plan, a message archived, a change applied by an assistant. It stays until it is dismissed or the next action replaces it, so it is not missed the way a toast is by someone using a screen reader, a magnifier or a slow hand. For news that needs no answer and is unrelated to one place use toaster; for a decision before the action use dialog.
```tsx
{removed ? (
Lunch was removed from Saturday.
Undo
setRemoved(null)} />
) : null}
```
### video-player
The parts of a video player around a `` element the project renders: a frame that keeps its shape, controls that step back while it plays, play, mute, volume, time, a scrubber, captions, speed, full screen, and words for loading and failure.
Use it: Any video a person controls: a clip on a page, a lesson, a recording. The project gives the element its sources (a file, or HLS attached to the element); the parts only drive it, so compose the ones the clip needs. Nothing plays by itself: for a silent, looping decoration use a plain `` with its own pause control. For sound alone use audio-player; for a picture viewer use lightbox.
```tsx
```
### virtual-list
A long list or grid that renders only the rows in view: thousands of items of any height in a box that scrolls, or down a page that scrolls with the window, each still announced with its position in the whole list, with a way to go to an item and to come back to where the person was.
Use it: More items than the page should hold at once (a few hundred or more): a feed, a log, search results, a picture library. Rows may have any height: each is measured once it is drawn and the rest are estimated, and the view does not jump when a row above it turns out taller. Give the box a height and a name (`aria-label`); or, where the list is the page (a feed, results under a header), `scroll="window"` and no height: it then grows to its full length and the window scrolls it. For a short list render the rows plainly; for a conversation that grows at the bottom use thread; for pages of results use pagination. Written here on ResizeObserver instead of adding a virtualisation package: a headless one would bring the offsets but not the roles, the positions for screen readers, the kept focus or the restoration, which are most of this file.
```tsx
// Rows of any height
messages[index].id} aria-label="Messages" className="h-96 rounded-surface border">
{(index) => {messages[index].text} }
// A grid, as many columns as fit; the place is remembered for this tab
{(index) => }
// The page scrolls, not a box: no height, and rows above and below the window are not rendered
results[index].id} aria-label="Results">
{(index) => }
// Going to an item
const list = useRef(null);
{(index) => Line {index + 1}
}
list.current?.scrollToIndex(4999, { align: "center" })}>Go to line 5,000
```
### visually-hidden
Keeps its content out of sight and still read by screen readers.
Use it: Words that sighted people get from the layout and others need said: a heading for a region, the unit after a figure, the table behind a chart. Use asChild to hide an element of your own. On a single element the `sr-only` utility does the same; never use it to hide content from everyone, which is `hidden`.
```tsx
Opens in a new tab
Search results
```
### wizard
The shell of a guided task done one step at a time inside a card: a title with "Step 2 of 5", a rail of the steps, the current step, and Back, Skip and a main button named after what the step does.
Use it: A task that is easier one question at a time and has a known order: a booking, a set-up, an application. It keeps where one is (controlled or not), moves focus to each new step's heading, and blocks the main button with a stated reason while a step is not answered. Where a server decides what comes next, control it: give `step`, and `onNext`, `onBack` and `onSkip` in place of the wizard's own moves, with `pending` while the answer is on its way; the step still slides in and its heading still takes focus when `step` changes. For a short form show all the fields at once (field); for the rail alone use steps; for unordered sections use tabs or accordion. What each step contains is yours: the wizard holds no answers.
```tsx
const [people, setPeople] = useState(0);
0, blockedReason: "Say how many people are coming." },
{ id: "extras", label: "Extras", optional: true },
{ id: "review", label: "Review" },
]}
defaultStep="dates"
onComplete={book}
>
Book a table
…
…
…
Back
Skip
{step === "review" ? "Confirm" : "Continue"}
// Driven from outside: the server says which step is next, and the rail's states are the project's
({ id: item.id, label: item.label, optional: item.optional, state: item.skipped ? "skipped" : undefined }))}
step={flow.current}
pending={saving}
onNext={(current) => submit(current.id)}
onBack={(current) => goBackFrom(current.id)}
onSkip={(current) => skip(current.id)}
>…
```
## Layout
### aspect
Holds its content at a fixed width-to-height ratio, so space is reserved before an image, video or canvas loads.
Use it: Media whose size is not known until it loads, or a tile that must keep its shape at any width. Make the child fill it (`size-full object-cover`). For plain CSS needs the `aspect-video` utility is enough.
```tsx
```
### bento-grid
A grid of flat cards of unequal sizes. One column on a phone, two on a tablet, then 2, 3, 4 or 6: decided by the grid's own width, so it works inside any container.
Use it: Showing several features, figures or pieces of media as one composed block. Cells take `span` and `rowSpan`; spans are clamped to the columns there are. For equal cards use grid; for a single surface use card.
```tsx
// Feature block: one wide lead cell, two small ones, a full-width strip.
Themable from one place
Light or dark, square to round, any highlight colour.
Accessible
Fast
Yours to edit
// Dashboard: four figures on top, a wide chart beside a tall list.
…chart…
…recent activity…
// Link mosaic: six columns, mixed sizes, gaps back-filled, every cell a link.
…
…
…
…
…
```
### container
Centres content at the page width with the page gutter on both sides. Four sizes: narrow, page, wide, full.
Use it: Around the content of every page band so edges line up down the page. "narrow" for reading text, "wide" for galleries and dashboards, "full" to keep only the gutter. Section already wraps its children in one.
```tsx
Pricing
Long-form text…
```
### grid
A responsive grid of equal columns that fits as many as the width allows, from a minimum column width. No breakpoints.
Use it: A set of like items: cards, logos, stats, thumbnails. It reflows inside any width, including a sidebar. For tiles of different sizes use bento-grid; for two fixed columns use split.
```tsx
…
…
…
{logos}
```
### map-frame
The frame around a map, not a map: it holds the map's size, shows a still until the person asks for the map, keeps a text list beside it, and takes the map to full screen and back. The map engine is yours.
Use it: Any page that shows a map from any engine (MapLibre, Leaflet, a hosted maps script). It gives the map what an engine does not: no request to a third party before the person presses the button (put the line about that in MapFrameNotice), no layout shift, the same information as a list (MapFrameList) so that the map is never the only way to it, a way to skip past the map with the keyboard, and full screen that behaves as a modal. For a still picture of a place with no interaction use an image in aspect.
```tsx
Show the map
The map is loaded from Example Maps, which will see your address.
{stops.map((stop) => {stop.name}, {stop.address} )}
```
### marquee
A row that scrolls sideways without end. It pauses on hover and on keyboard focus, and under reduced motion it is an ordinary wrapped row.
Use it: A strip of logos, short quotes or tags where no single item must be read. Not for content the reader needs: everything is also in the markup once, but it moves. For a few items that fit, use stack or grid.
```tsx
Design
Build
Launch
```
### section
A band of a page with consistent vertical rhythm, an optional eyebrow, title and description, and three tones: default, muted, inverse.
Use it: Every top-level block of a marketing or content page. "inverse" makes a dark band on a light page and re-themes everything inside it. Inside an app screen use stack and card instead.
```tsx
Plain content, no header.
```
### split
Two columns, usually media beside text, that stack into one on a narrow width. A ratio between the columns and a reverse option.
Use it: A feature row, a hero with an image, a form beside its explanation. Give it exactly two children. Alternate `reverse` down a page for a zigzag. For more than two columns use grid.
```tsx
See everything at once
One screen for the whole week.
…
…
```
### stack
A flex row or column with a gap from a fixed scale, and props for alignment, distribution and wrapping.
Use it: Spacing a run of siblings evenly: form fields, a button row, a header with actions. For columns that reflow by width use grid; for unequal tiles use bento-grid.
```tsx
Title
Body
Plan
Change
```
## Motion and transitions
### film-stage
A stage for a sequence of timed scenes with a transport: it owns the clock and the chrome (play, time bar, speed, sound), mounts the scene for the current moment, cuts or crossfades between scenes, and can draw any moment on request for export.
Use it: Content the project draws itself from a time: an animated explainer, a story in scenes, a slideshow with narration, a film assembled from markup, SVG or canvas. Each scene gets its own local time and draws from it, so any frame can be drawn again exactly. The stage is the clock other things follow: scrubber, scene-strip, captions and hotspots work inside it as they do inside video-player, and any number of sounds (a clip for each narrated line, a bed under them) are kept in step, each from its own start for its own length. For a video or sound file use video-player or audio-player; for motion tied to scrolling use scroll-scene; for a set of pictures a person pages through use carousel.
```tsx
const scenes = [
{ id: "title", duration: 4, label: "Title", children: How a pot is thrown },
{ id: "wheel", duration: 6, label: "On the wheel", transition: "crossfade" as const, render: ({ progress }) => },
];
// One clip for each narrated line and a bed under them; each follows the clock, the speed, a seek and the mute
track(scene.id)} aria-label="How a pot is thrown">
{lines.map((line) => )}
// Export: a headless browser draws each frame, with no timer running on the page
…
// in the page, from the exporter: await window.__filmStage.main.renderAt(frame / 30), then take the picture
```
### layout-transition
A shared element that animates from one place to another: render Morph with the same layoutId in two places and it travels between them.
Use it: A tabs or navigation indicator that slides to the active item, a card that grows into its detail view, a selection highlight. Both places must be in the same React tree. Between pages use view-transition; for content that only appears and disappears use presence.
```tsx
const [active, setActive] = useState("overview");
{["overview", "pricing", "docs"].map((tab) => (
setActive(tab)} className="relative h-control rounded-control px-4 text-sm">
{active === tab ? : null}
{tab}
))}
```
### magnetic
A wrapper whose child is gently pulled toward the pointer while it is hovered, and springs back when the pointer leaves.
Use it: The one main call to action on a marketing page, or an icon button that should feel alive. Not for every button, not inside dense interfaces, and it does nothing on touch screens.
```tsx
Start a project
```
### number-ticker
A number that counts up to its value when it scrolls into view, formatted with Intl.NumberFormat.
Use it: A headline statistic: customers, revenue, a percentage. Not for values that update live (render those directly), and not for more than a few on one screen.
```tsx
```
### page-transition
Wraps page content and plays a short enter (a fade and a small rise) each time the route changes.
Use it: The content area of an app or site, once, in the layout. The first page load is not animated. Where the browser supports it and elements should morph between pages, use view-transition instead; do not use both.
```tsx
// app/template.tsx (Next.js). A template is re-created on navigation; the pathname is the key.
"use client";
import { usePathname } from "next/navigation";
import type { ReactNode } from "react";
import { PageTransition } from "@/components/motion/page-transition";
export default function Template({ children }: { children: ReactNode }) {
return {children} ;
}
```
### parallax
A clipped frame whose layer moves at a different speed from the page as it scrolls past.
Use it: A background image or a decorative layer behind a section. The frame needs a height of its own (an aspect ratio or a fixed height). Not for text that must be read while it moves; for a pinned, scroll-told sequence use scroll-scene.
```tsx
```
### presence
Animates its children in when they are shown and out before they are removed.
Use it: Conditional UI that is not a Radix primitive: an inline notice, a revealed panel, a step that swaps. Radix dialogs, popovers and menus already animate with their own classes; for content entering on scroll use reveal.
```tsx
const [open, setOpen] = useState(false);
setOpen((value) => !value)}>Toggle
Saved. Your changes are live.
```
### reveal
Fades and moves its content into place when it scrolls into view.
Use it: A section, card or image that should arrive as the page is read. For a list revealed one after another use stagger; for a heading use text-reveal; for conditional UI that mounts and unmounts use presence.
```tsx
Built to be owned
```
### scroll-progress
A thin bar fixed to the top of the viewport that fills as the page, or one element, is scrolled through.
Use it: Long reading pages: an article, documentation, a case study. Pass `target` to follow the article rather than the whole page. Not a loading indicator (use a progress control for that).
```tsx
const article = useRef(null);
…
```
### scroll-scene
A tall section with a pinned viewport whose children are driven by scroll progress from 0 to 1, for scroll-told sequences.
Use it: A product story told as the visitor scrolls: steps that replace each other, a device that turns, a diagram that builds. Use sparingly, one or two per page. For a simple entrance use reveal; for a drifting background use parallax.
```tsx
Design
Build
Launch
{(progress, active) => }
function Dial({ progress, still }: { progress: MotionValue; still: boolean }) {
const rotate = useTransform(progress, [0, 1], [0, 180]);
return ;
}
```
### spotlight
A surface on which a soft light in the highlight colour follows the pointer.
Use it: A hero panel, a feature card or a call-to-action band that should respond to the pointer. Give it a border and a background like any surface. Decoration only: it does nothing on touch screens, so never rely on it to show something.
```tsx
Made to be changed
Every component is yours to edit.
…
```
### stagger
A container whose items fade and move into place one after another when it scrolls into view.
Use it: A grid of cards, a feature list, a row of logos. For one block use reveal; for the words of a heading use text-reveal.
```tsx
Design
Build
Launch
```
### text-reveal
Reveals a heading word by word, or line by line, when it scrolls into view.
Use it: A headline or a short statement. Not for paragraphs of body text (use reveal on the block), and not for text that changes while it is shown.
```tsx
Websites, apps and systems that last
We design the brand, build the product and stay to run it.
```
### tilt
A wrapper that tilts its content in 3D toward the pointer on hover and springs back, with an optional glare.
Use it: A featured card, a product shot, a pricing plan worth lifting off the page. One or a few per view; not for forms or anything read at length, and it does nothing on touch screens.
```tsx
Studio plan
Everything, for one team
```
### view-transition
View transitions two ways: wrappers over React's own (a shared element that morphs between two places, a boundary that cross-fades what changes inside it), and helpers for the browser's API (run an update as a transition, name an element, a link that navigates inside a transition).
Use it: Moving between pages or between two states of a view, where an element in the old view should become one in the new. Use the React wrappers (SharedElement, TransitionBoundary) when the change is a React transition: a state update inside startTransition, a Suspense boundary revealing, a navigation by a router that uses transitions (Next.js). React then starts the browser's transition itself. Use the browser helpers (startViewTransition, ViewTransitionName, TransitionLink) when nothing in the tree uses React's component: a synchronous update, a router that does not use transitions, an element that stays mounted while the view around it changes. Do not mix the two for one update: React's documentation says not to call document.startViewTransition yourself around an update it is already animating. Both degrade to an instant change where the API is missing, and the theme switches them off under reduced motion. For a shared element that must be interrupted mid-way use layout-transition; for a simple enter on route change use page-transition.
```tsx
// React's way: the same name in two places; the update runs in a transition.
const [open, setOpen] = useState(false);
{open ? (
) : (
startTransition(() => setOpen(true))}>
)}
// The browser's way. A link that navigates inside a view transition; in Next.js pass router.push:
Atlas
// The same name on the list page and on the detail page: the image morphs from one to the other.
// A state change in place. flushSync (from react-dom) makes React apply it before the browser's snapshot.
startViewTransition(() => flushSync(() => setLayout("grid")))}>Grid
```
## 3D
### floating-shapes
A few simple solids (icosahedron, torus, box, octahedron) floating and turning slowly, flat-shaded or wireframe, coloured from theme variables.
Use it: An abstract, geometric accent for a hero or a feature section. Use it inside scene. For a single soft object use orb; to show a real object use model-stage.
```tsx
```
### globe
A dotted globe that turns slowly and can be dragged to spin, with optional highlighted markers by latitude and longitude.
Use it: Showing reach or places at a glance: offices, regions, where requests come from. Use it inside scene. For exact values per place use a table or bar-chart; the globe is not a chart.
```tsx
```
### model-stage
A turntable for any mesh or group: centres and fits it, turns it slowly, and lets the pointer orbit it within limits.
Use it: Showing one object: a product, a loaded model, a shape of your own. Use it inside scene. For decoration without a subject use orb or floating-shapes.
```tsx
```
### model-viewer
Shows one 3D model that a person can turn, zoom and reset: a glTF or GLB file, or Gaussian splats (.spz, .ply, .splat, .ksplat, .sog), with a poster and progress while it loads and a still fallback where 3D cannot run.
Use it: A file to look at from every side: an object, a product, a scanned place. It is a whole viewer, not a part of scene: for your own meshes inside a react-three-fiber canvas use scene with model-stage. Nothing heavy is in this file: three.js is fetched when the viewer comes near the screen, its glTF loader only for glTF, and Spark (`@sparkjsdev/spark`, installed with this item) only when the file is splats. glTF that carries splats in an extension is not read (Spark has no glTF loader); Draco, Meshopt and KTX2 compression need their decoders set in `configureLoader`. Plain wheel and vertical swipes scroll the page: zoom is pinch, Ctrl with the wheel, the keys or the buttons. To compare two models, give two viewers the same `view` and `bounds` inside compare-slider, with `children={null}` and buttons of your own that change the shared view.
```tsx
// Splats, turning by itself (never under reduced motion), with a hand-off to AR on phones
// Two viewers, one camera
const [view, setView] = useState({ azimuth: 0, polar: 15, zoom: 1 });
const frame = { center: [0, 4, 0], radius: 9 } as const; // one sphere for both, so they keep their sizes and line up
```
### orb
A softly morphing sphere in the highlight colour, lit at its rim so it reads on light and dark grounds, leaning gently toward the pointer.
Use it: A calm focal object for a hero or an empty state. Use it inside scene. For many small elements use particle-field; for a product or object of your own use model-stage.
```tsx
```
### particle-field
A field of small round points drifting slowly, with depth that shifts as the pointer moves.
Use it: A quiet moving ground behind a hero or a section. Use it inside scene and keep text on top readable. For one focal object use orb; for data use the viz components, never particles.
```tsx
```
### scene
The wrapper every 3D component is used inside: a transparent WebGL canvas that mounts late, pauses off screen and falls back to a static block.
Use it: Around orb, particle-field, floating-shapes, globe, model-stage or your own react-three-fiber content. Give it a size through the parent or `aspect`. For a decorative background that needs no 3D, use a plain token-coloured block.
```tsx
}>
```
## Visualisation
### area-chart
A line chart with the space under each line filled flat at low opacity, optionally stacked so the series add up to a total.
Use it: One series over time whose volume matters, or a few series that add up to a whole (`stacked`). To compare series that cross each other use line-chart: overlapping fills hide one another.
```tsx
```
### bar-chart
A bar chart, vertical or horizontal, grouped or stacked, always measured from zero, with a tooltip on hover and arrow-key reading.
Use it: Comparing amounts across categories. Use `orientation="horizontal"` for long names or a ranking, `stacked` when the series add up to a total. For change over many points in time use line-chart; for a single number use a stat, not one bar.
```tsx
```
### chart
The shared parts every chart is built from: a container that measures itself and carries the text alternative, an SVG root, a tooltip, a legend, series styles, and axis and format helpers.
Use it: Building a chart of your own that should match the others. For the common forms use line-chart, area-chart, bar-chart, donut-chart, sparkline, heatmap or radial-progress directly.
```tsx
{({ width, height }) => (
)}
```
### donut-chart
A ring showing how one whole splits into at most five parts, with a label in the centre and each part's value and share in the legend.
Use it: Parts of a whole at a glance, when there are few parts and they differ clearly. To compare parts that are close in size, or more than five, use bar-chart with `orientation="horizontal"`; for one ratio against a limit use radial-progress.
```tsx
```
### heatmap
A matrix of cells (day by hour, for example) coloured on one-hue scale from faint to the highlight colour, with a tooltip, arrow-key reading and a scale legend.
Use it: Spotting patterns across two categories at once: when it is busy, which pairs stand out. To compare exact amounts use bar-chart; for one row of values over time use line-chart.
```tsx
```
### line-chart
A line chart of one or more series over a numeric or time x, with a crosshair tooltip, arrow-key reading and labels at the line ends.
Use it: Change over time or along a number, for up to about five series on one shared scale. For a single series whose volume matters use area-chart; for separate categories use bar-chart; never plot two different units against two y axes, use two charts.
```tsx
```
### radial-progress
A ring gauge for one value against a limit, with the value and a label in the centre.
Use it: One ratio: a quota used, a score, a goal reached. Size it with a width class (`w-32` by default). For several ratios side by side use a list of bars (bar-chart horizontal), not a ring each; for parts of a whole use donut-chart.
```tsx
`${value} of 5`} className="w-40" />
```
### sparkline
A tiny line, area or bar chart with no axes, for a stat tile or a table cell, described in words for assistive technology.
Use it: The shape of a trend beside a number that carries the value. Size it with classes (`h-8 w-24` by default). When the reader needs to read values off it, use line-chart or bar-chart.
```tsx
```