r.id} bordered />;
}
render(`
container (padding, alignment, sticky, a11y); `cell` only supplies the content.
```tsx
function CustomCellDemo() {
const data = [
{ id: '1', name: 'Ada Lovelace', role: 'admin' },
{ id: '2', name: 'Linus Torvalds', role: 'user' },
];
const columns = [
{ id: 'name', header: 'Name', accessor: 'name' },
{
id: 'role',
header: 'Role',
cell: ({ row }) => (
{row.original.role}
),
},
{
id: 'actions',
header: '',
align: 'end',
cell: ({ row }) => (
alert('Edit ' + row.original.name)}>
Edit
),
},
];
return r.id} />;
}
render(
¹ Spar's `Select` has no multi mode yet, so `multi-select` currently renders
the same `Checkbox` list as `checkbox`.
```tsx
function FilterPresetDemo() {
const data = [
{ id: '1', name: 'Ada Lovelace', role: 'admin' },
{ id: '2', name: 'Linus Torvalds', role: 'user' },
{ id: '3', name: 'Grace Hopper', role: 'admin' },
{ id: '4', name: 'Alan Turing', role: 'user' },
];
const columns = [
// Bare string preset — the shortest form.
{ id: 'name', header: 'Name', accessor: 'name', filter: 'text' },
// Object preset — a choice control needs its options.
{
id: 'role',
header: 'Role',
accessor: 'role',
filter: { type: 'checkbox', options: [
{ label: 'Admin', value: 'admin' },
{ label: 'User', value: 'user' },
] },
},
];
return r.id} />;
}
render(
Why both tiers?
The legacy takeoff-ui filter was a closed `type` enum, which could never
cover every column's needs, so customization ended up blocked on a library
change. Every mature table (Mantine/Material React Table, AG Grid, MUI X)
instead layers a short preset under a render escape hatch. Presets keep
the 90% case one-line; `render` (the same inversion as `cell` /
`expansion.render`) leaves the rest fully open.
```tsx
function FilterCustomDemo() {
const data = [
{ id: '1', name: 'Ada Lovelace', score: 91 },
{ id: '2', name: 'Linus Torvalds', score: 64 },
{ id: '3', name: 'Grace Hopper', score: 88 },
{ id: '4', name: 'Alan Turing', score: 73 },
];
const columns = [
{ id: 'name', header: 'Name', accessor: 'name', filter: 'text' },
{
id: 'score',
header: 'Score',
accessor: 'score',
align: 'end',
// Escape hatch: a "minimum score" filter no preset covers. You render
// the control + supply the matching predicate; Table owns the popover.
filter: {
isActive: (value) => value != null && value !== '',
filterFn: (row, columnId, value) =>
value == null || value === '' ? true : row.getValue(columnId) >= Number(value),
render: ({ value, setValue }) => (
setValue(e.target.value || undefined)}
/>
),
},
},
];
return r.id} />;
}
render( r.id}
expansion={{ render: (row) => {row.note}
}}
/>
);
}
render({row.original.name}
),
},
{ id: 'headcount', header: 'Headcount', accessor: 'headcount', align: 'end' },
];
return (
r.id}
getSubRows={(row) => row.children}
expansion={{ defaultValue: true }}
bordered
/>
);
}
render(
{row.original.role}
),
},
{ id: 'city', header: 'City', accessor: 'city', width: 130 },
{ id: 'country', header: 'Country', accessor: 'country', width: 100, align: 'center' },
{ id: 'age', header: 'Age', accessor: 'age', width: 80, align: 'end', sortable: true },
{ id: 'salary', header: 'Salary', accessor: 'salary', width: 110, align: 'end', sortable: true,
cell: ({ row }) => '$' + row.original.salary.toLocaleString() },
{ id: 'status', header: 'Status', accessor: 'status', width: 110,
filter: { type: 'checkbox', options: [
{ label: 'Active', value: 'active' },
{ label: 'Inactive', value: 'inactive' },
]},
cell: ({ row }) => (
{row.original.status}
),
},
{ id: 'actions', header: '', align: 'end', sticky: 'right', width: 80,
cell: ({ row }) => (
alert('Edit ' + row.original.name)}>
Edit
),
},
];
return (
r.id}
sorting={{ multi: true }}
selection={{ mode: 'multiple' }}
pagination={{ pageSize: 6, pageSizeOptions: [6, 12] }}
slotProps={{ tableViewport: { style: { maxHeight: 280 } } }}
stickyHeader
striped
bordered
/>
);
}
render(
{['xsmall', 'small', 'base'].map((value) => (
setSize(value)}
>
{value}
))}
r.id} size={size} bordered />
);
}
render( r.id}
bordered
emptyState={
No flights match your filters.
}
/>
);
}
render(
setLoading((v) => !v)}>
{loading ? 'Stop loading' : 'Start loading'}
r.id} loading={loading} bordered />
);
}
render( row.id}
manual
sorting={{ value: sorting, onChange: setSorting }}
filtering={{ value: filters, onChange: setFilters }}
pagination={{
pageSize,
pageIndex,
rowCount: page.total,
onChange: setPagination,
}}
onDataRequest={({ pagination, sorting, filters }) =>
fetchPage({ pagination, sorting, filters })
}
loading={isFetching}
/>
```
## Exporting data
Table ships **no export engine** — it exposes the current filtered + sorted rows
as a plain value projection via `getExportRows(tableRef.current)`. Formatting
and file download (CSV / Excel / PDF) stay on your side, keeping those heavy
dependencies out of the bundle.
```tsx
import { Table, getExportRows } from '@takeoff-ui/react-spar';
const tableRef = useRef(null);
r.id}
tableRef={tableRef}
/>;
// later — e.g. a "Download CSV" button:
const rowsToExport = getExportRows(tableRef.current); // Array>
```
## Accessibility
- Renders a native `` / `` / ` ` / `` /
` `, so screen-reader table navigation, header association, and row/column
counts come for free.
- Sortable headers are real ``s (Enter / Space toggle sorting) and the
`` carries `aria-sort` (`ascending` | `descending` | `none`).
- Row selection composes Spar `Checkbox` (multiple) or `Radio` (single) with
accessible names; the select-all header checkbox is multiple-mode only.
- Pagination is a labelled `navigation` region; the page-size control is a Spar
`Select` with an accessible name, and the nav buttons carry `aria-label`s.
- The loading overlay surfaces the Spar `Spinner` (`role="status"`) and the
table is marked `aria-busy` while `loading`.
| Key | Behavior |
| ----------------------------------- | ----------------------------------------------- |
| Tab | Move between interactive controls in the table. |
| Enter / Space | Toggle sorting on a focused sortable header. |
## API Reference
### Table {#table}
See [TanStack Table docs](https://tanstack.com/table/latest/docs/introduction)
for primitive behavior.
#### Props {#table-props}
| Name | Type | Default | Description |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| data | `TData[]` | - | Row data. In `manual` mode this is the current server page. |
| columns | `TableColumnDef[]` | - | Column definitions. See `TableColumnDef`. |
| getRowId | `(row: TData, index: number) => string` | - | Stable row identity (single source of truth). |
| size | `TableSize` | 'base' | Density scale. |
| striped | `boolean` | false | Zebra-stripe rows → `data-striped`. |
| bordered | `boolean` | false | Cell borders → `data-bordered`. |
| stickyHeader | `boolean` | false | Pin the header row during vertical scroll → `data-sticky-header`. |
| manual | `boolean` | false | Server mode. When `true`, Table processes nothing in-memory — it maps to TanStack's `manualSorting`/`manualFiltering`/`manualPagination` and emits a single bundled `onDataRequest` (RFC §3.3). |
| selection | `TableSelectionConfig` | - | Row selection (single/multiple + select-all). Composes Spar Checkbox/Radio. |
| sorting | `TableSortingConfig` | - | Sorting (multi-sort opt-in). |
| filtering | `TableFilteringConfig` | - | Column filtering. Filter UIs render in a Spar `Popover`. |
| expansion | `TableExpansionConfig` | - | Expandable rows with a render-prop body. |
| pagination | `boolean \| TablePaginationConfig` | - | Pagination. `true` enables it with defaults; an object configures it. |
| loading | `boolean` | false | Loading state → `data-loading` + a loading overlay. |
| emptyState | `React.ReactNode` | - | Content rendered when there are no rows. |
| getSubRows | `(row: TData) => TData[]` | - | Sub-row reader for **tree data** (feeds TanStack `getSubRows`). Pair it with `expansion` (sans `render`) so expanding a row reveals its flattened sub-rows. When `getSubRows` is omitted, expansion falls back to the detail-panel mode driven by `expansion.render`. Supplying both keeps tree mode and suppresses the detail panel. |
| tableRef | `Ref \| null>` | - | Escape hatch for the rare imperative need — receives the TanStack table instance (RFC §2.3: controlled props + an optional instance ref, never an imperative `@Method` surface). Also the access point for `getExportRows()`. |
| classNames | `Partial>` | - | Per-slot class name overrides. |
| slotProps | `Partial>>` | - | Per-slot HTML attribute overrides. |
| className | `string` | - | Appends custom classes to the root container. |
#### Events {#table-events}
| Name | Type | Default | Description |
| ---------------------------------- | -------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------- |
| onDataRequest | `(request: TableDataRequest) => void` | - | Bundled server data-request callback (`manual` mode). See `TableDataRequest`. |
#### Data attributes {#table-data-attributes}
| Attribute | Applied when | Purpose |
| --------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| data-slot="root" | Always | Stable selector for the root container. |
| data-slot="table-viewport" | Always | The table-only horizontal/vertical scroll container; pagination remains outside it. |
| data-size | Always | Reflects the resolved `size` (density) so recipes can scope cell padding. |
| data-striped | When `striped` is true. | Enables zebra striping on body rows. |
| data-bordered | When `bordered` is true. | Adds vertical separators between columns. |
| data-sticky-header | When `stickyHeader` is true. | Pins the header row during vertical scroll. |
| data-scrolled | On the table viewport while `scrollTop > 0`. | Adds sticky-header elevation only after vertical scrolling begins. |
| data-loading | When `loading` is true. | Shows the loading overlay; the table is also marked `aria-busy`. |
| data-align | On every header/body cell with an `align` (or column `meta.headerAlign`). | Drives cell `text-align` (`start` \| `center` \| `end`). |
| data-sticky | On cells of a column with `sticky: "left" \| "right"`. | Pins the column; per-edge offset + z-index are applied inline. |
| aria-sort | On sortable header cells. | A11y sort state (`ascending` \| `descending` \| `none`); the sort arrow mirrors it via `data-direction`. |
| data-selected | On a selected body row. | Theme hook for the selected-row background. |
### Type Definitions {#table-type-definitions}
| Name | Definition |
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| TableSize | `'xsmall' \| 'small' \| 'base'` |
| TableSelectionConfig | `{ mode: 'single' \| 'multiple' }` |
| TableSortingConfig | `{ multi?: boolean }` |
| TableFilteringConfig | `{ value?: T; defaultValue?: T; onChange?: (value: T) => void }` |
| TablePaginationConfig | `{ pageSize?: number; pageIndex?: number; pageSizeOptions?: number[]; rowCount?: number; onChange?: (pagination: PaginationState) => void }` |
| TableSlot | `\| 'root' \| 'tableViewport' \| 'table' \| 'header' \| 'headerRow' \| 'headerCell' \| 'headerContent' \| 'sortTrigger' \| 'sortIcon' \| 'body' \| 'row' \| 'cell' \| 'selectionCell' \| 'expandCell' \| 'expandButton' \| 'expandedRow' \| 'filterButton' \| 'filterPanel' \| 'pagination' \| 'paginationInfo' \| 'paginationNav' \| 'paginationActions' \| 'paginationSize' \| 'paginationGoToPage' \| 'empty' \| 'loading'` |
| TableDataRequest | `{ pagination: PaginationState; sorting: SortingState; filters: ColumnFiltersState }` |
## When to use
Rendering tabular data with any of sorting, filtering, pagination, row selection, expandable/tree rows, sticky columns, loading/empty states, or server-side paging. `getRowId` is mandatory — it is the identity source row selection keys on.
---
# Progress
`Progress` shows how far a task has advanced as a horizontal bar (`'linear'`) or
a ring (`'circular'`). The anatomy is the same for both appearances: the root is
the wrapper and accessibility owner, `Progress.Track` is the rail (the linear
rail bar, or the ring svg drawing the rail circle), `Progress.Indicator` is the
filled portion, and `Progress.Value` composes decorative value or status text —
in flow next to the linear track, centered inside the circular ring.
Set `indeterminate` while the work's extent is unknown — the indicator loops a
sweep animation instead of a fill. For standalone loading states with no
progress semantics, a [`Spinner`](/docs/components/spinner) is still the right
component.
The root carries `role="progressbar"` with the full `aria-valuemin` /
`aria-valuemax` / `aria-valuenow` surface, so assistive technology announces the
value without extra wiring. Compose it inside a
[`Field`](/docs/components/input#using-with-field) with `Field.Label` for a
visible label — the accessible name and the field's disabled state wire up
automatically.
## Usage
```tsx
import { Field, Progress } from '@takeoff-ui/react-spar';
```
```tsx
Upload progress
%40
%66
```
## Playground
```tsx
function PlaygroundDemo() {
const [value, setValue] = React.useState(0);
React.useEffect(() => {
const timer = setInterval(() => {
setValue(prev => (prev >= 100 ? 0 : Math.min(prev + 4, 100)));
}, 400);
return () => clearInterval(timer);
}, []);
return (
Uploading files
%{value}
%{value}
);
}
render(
{variants.map(variant => (
{variant}
%60
))}
{[25, 50, 75].map(value => (
%{value}
))}
{sizes.map(size => (
{size}
%60
))}
{sizes.map(size => (
%60
))}
);
}
render(
Block progress
%40
Inline progress
%40
);
}
render(>` | - | Per-slot class name overrides. |
| slotProps | `Partial>>` | - | Per-slot HTML attribute overrides. |
| className | `string` | - | Appends custom classes to the root slot of this part. |
#### Data attributes {#progress-data-attributes}
| Attribute | Applied when | Purpose |
| ----------------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
| data-type | Always | Reflects the resolved `appearance` prop (`linear` \| `circular`). |
| data-size | Always | Reflects the resolved `size` prop so recipes can scale the bar or ring. |
| data-variant | Always | Reflects the resolved `variant` prop so theme recipes can recolor the fill. |
| data-disabled | disabled (own prop or inherited from a surrounding `Field`) | Mutes the fill color through the recipe. |
| data-indeterminate | `indeterminate` | Marks the indeterminate state; `aria-valuenow` is dropped alongside it. |
| data-complete | Determinate and the clamped `value` reaches `max` | Styling hook for finished states (e.g. a success fill at 100%). It flips the instant the value reaches `max` — the fill’s 0.3s transition may still be catching up visually, so completion styling leads the fill slightly. |
### Progress.Track {#progress-track}
#### Data attributes {#progress-track-data-attributes}
| Attribute | Applied when | Purpose |
| ----------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------ |
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
| data-slot="rail" | appearance="circular" | The rail `` the ring svg draws; style or override it via `classNames.rail` / `slotProps.rail`. |
| data-type | Always | Reflects the root’s resolved `appearance` so the part’s recipe styles itself without root selectors. |
### Progress.Indicator {#progress-indicator}
#### Data attributes {#progress-indicator-data-attributes}
| Attribute | Applied when | Purpose |
| ----------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------- |
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
| data-type | Always | Reflects the root’s resolved `appearance` so the part’s recipe styles itself without root selectors. |
| data-indeterminate | `indeterminate` | Drives the looping sweep animation instead of a written fill. |
### Progress.Value {#progress-value}
#### Data attributes {#progress-value-data-attributes}
| Attribute | Applied when | Purpose |
| ----------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------- |
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
| data-type | Always | Reflects the root’s resolved `appearance` so the part’s recipe styles itself without root selectors. |
### Type Definitions {#progress-type-definitions}
| Name | Definition |
| ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| ProgressAppearance | `'linear' \| 'circular'` |
| ProgressSize | `'small' \| 'base' \| 'large'` |
| ProgressVariant | `'primary' \| 'info' \| 'success' \| 'danger' \| 'warning'` |
| ProgressTrackSlot | `'root' \| 'rail'` |
## When to use
Work with a known percentage — file uploads, imports, quota and storage meters, multi-item batch jobs — or a bar-shaped indeterminate treatment for a long-running task. Not this — use `takeoff-spinner` for short waits where a bar would be visual noise, and `takeoff-skeleton` when you are holding the shape of content that is still loading.
---
# Spinner
A compact indeterminate loading indicator with built-in status semantics.
## Usage
```tsx
import { Spinner } from '@takeoff-ui/react-spar';
```
```tsx
);
}
render(
);
}
render(
);
}
render(
);
}
render(
Loading flights
Saving
Preparing
);
}
render(
);
}
render(>` | - | Per-slot extra classes. |
| slotProps | `Partial>>` | - | Per-slot HTML-attribute overrides. |
| className | `string` | - | Appends custom classes to the root slot. |
| aria-label | `string` | 'Loading' | Accessible name for the loading status. Override it for domain-specific loading text. |
| aria-labelledby | `string` | - | ID reference for visible loading text. When provided, the default `aria-label` is not applied. |
| aria-hidden | `boolean` | false | Hides a decorative spinner from assistive technology. When true, status role and default accessible name are not applied. |
#### Data attributes {#spinner-data-attributes}
| Attribute | Applied when | Purpose |
| ----------------------------------------------- | ------------ | ----------------------------------------------------------------- |
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
| data-variant | Always | Reflects the resolved `variant` prop for theme recipe scoping. |
| data-size | Always | Reflects the resolved `size` prop for theme recipe scoping. |
| data-type | Always | Reflects the resolved `appearance` prop for theme recipe scoping. |
### Type Definitions {#spinner-type-definitions}
| Name | Definition |
| ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| SpinnerSize | `'small' \| 'base' \| 'large' \| 'xlarge'` |
| SpinnerAppearance | `'rounded' \| 'dots' \| 'lines' \| 'pulse' \| 'threeDots' \| 'loader' \| 'logo'` |
| SpinnerVariant | `'primary' \| 'secondary' \| 'neutral' \| 'info' \| 'success' \| 'danger' \| 'warning'` |
| SpinnerSlot | `'root' \| 'indicator'` |
## When to use
Show ongoing, indeterminate activity (fetching, saving, processing) where progress is unknown. Not this — use a progress bar component for determinate percentage progress.
---
# Skeleton
`Skeleton` renders a visual placeholder for content that is still loading. Use
it when the final layout is known enough to reserve space and avoid a jumpy
transition when data arrives.
The component is decorative by default and renders `aria-hidden="true"`. Pair it
with surrounding loading text, a region state, or another status component when
the loading state needs to be announced.
## Usage
```tsx
import { Skeleton } from '@takeoff-ui/react-spar';
```
```tsx
);
}
render(>` | - | Per-slot extra classes. |
| slotProps | `Partial>>` | - | Per-slot HTML-attribute overrides. |
| className | `string` | - | Appends custom classes to the root slot. |
| aria-hidden | `boolean \| "true" \| "false"` | true | Keeps the placeholder out of the accessibility tree. Leave it hidden and expose loading context through nearby content. |
#### Data attributes {#skeleton-data-attributes}
| Attribute | Applied when | Purpose |
| -------------------------------------------------- | ------------------------ | ---------------------------------------------------------------- |
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
| data-type | Always | Reflects the resolved `shape` prop for theme recipe scoping. |
| data-animation | Always | Reflects the resolved `animation` prop for theme recipe scoping. |
| data-slot="shimmer" | Always on the inner span | Stable selector for the decorative shimmer strip. |
### Type Definitions {#skeleton-type-definitions}
| Name | Definition |
| -------------------------------------------------------------------------------------- | ---------------------------------------- |
| SkeletonShape | `'rectangle' \| 'circle'` |
| SkeletonAnimation | `'shimmer' \| 'none'` |
| SkeletonSlot | `'root' \| 'shimmer'` |
## When to use
First-load placeholders for content whose layout you already know — cards, list rows, avatars, text lines, table cells. Reach for it when leaving the space blank would make the page jump once data arrives. Not this — use `takeoff-spinner` for short, indeterminate waits with no known shape (a saving button, an inline refresh), and `takeoff-progress` when completion is measurable.
---
# Slider
`Slider` picks a number — or a `[min, max]` range — from a continuous scale. It
is a standalone component (no upstream Spar primitive), so the wrapper owns the
value math, the pointer dragging, and the full keyboard and ARIA surface. Each
thumb is its own `role="slider"` element, which is what assistive technology
reads and what the arrow keys drive.
## Usage
```tsx
import { Slider } from '@takeoff-ui/react-spar';
```
```tsx
Cabin temperature
v + '°C'}
>
{/* The root stacks its children; this row puts the readout
beside the rail, with the scale bounds under it. */}
);
}
render(
Price range
'$' + v}
/>
);
}
render(
Gradient stops
v + '%'}
/>
Committed: {stops.join(' · ')}
);
}
render(
Allowed window
{/* minDistance keeps the handles at least 20 apart — they clamp against
each other instead of crossing. */}
v + '%'}
/>
{range[0]}% – {range[1]}% (gap {range[1] - range[0]})
);
}
render(
Brightness
{/* onValueChange streams every frame; onValueChangeEnd fires once the
drag (or keypress) settles — drag the handle to see them diverge. */}
Live: {live} · Committed on release: {committed}
);
}
render(
{/* Pinned open — the bubble stays visible without interaction. */}
Always visible
v + '%'} />
{/* Hidden even on drag/focus — Slider.Value carries the number instead.
Field.Label and Slider.Value sit inside
so the readout reads
the live value from context and can share a row with the label. */}
v + '%'}>
Muted bubble
);
}
render(
{/* inverted (single) — the complement fills: from the thumb to the end. */}
Inverted fill
v + '%'} />
{/* inverted (range) — the fill sits outside the two handles. */}
Inverted range
v + '%'} />
{/* none — the fill is dropped; the rail and thumb stay. */}
No fill
);
}
render(
Altitude
v + '%'}
/>
With ticks
);
}
render(
);
}
render(
);
}
render(
Disabled
Read-only
Invalid
Pick a value under 50.
)}
Individual thumb disabled
{/* Only the lower handle is pinned; the upper one stays interactive. */}
);
}
render(
Warmth
v + '°'}
>
{/* Every part takes style / slotProps, so the whole slider is yours
to re-skin: a taller rail, a gradient fill, a ringed handle, and
a custom tooltip (shown on drag or focus). */}
{/* Pin the gradient to the full track width (448px = the max-w-md
container) so it maps to the absolute scale instead of stretching
across the current fill — a low value then stays blue. */}
{({ value, formatted }) => (
)}
);
}
render(>` | - | Per-slot class name overrides. |
| slotProps | `Partial>>` | - | Per-slot HTML attribute overrides. |
| className | `string` | - | Appends custom classes to the root slot. |
#### Events {#slider-events}
| Name | Type | Default | Description |
| ------------------------------------- | ------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| onValueChange | `(value: number \| number[]) => void` | - | Fired on every committed value change while interacting — each drag frame, keystroke, or track press. Receives a `number` by default and the full ascending array when `range` is set. |
| onValueChangeEnd | `(value: number \| number[]) => void` | - | Fired once at the end of an interaction with the final value: on pointer release after a drag or track press, and once per committed keystroke. Use it when only the settled value matters, while `onValueChange` streams the live value. |
#### Data attributes {#slider-data-attributes}
| Attribute | Applied when | Purpose |
| ----------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
| data-size | Always | Reflects the resolved `size` prop for theme recipe scoping (rail thickness and thumb diameter). |
| data-variant | Always | Reflects the resolved `variant` prop that drives the fill color. |
| data-orientation | Always | Reflects the resolved `orientation` prop. A vertical rail runs bottom-to-top and takes its height from its container, as a horizontal rail takes its width. |
| data-tooltip | Always | Reflects the resolved `tooltip` prop (`auto` \| `always` \| `never`) that controls when the value bubble shows. |
| data-track | Always | Reflects the resolved `track` prop (`normal` \| `inverted` \| `none`) that sets the rail fill mode; `inverted` fills the complement of the selection, `none` drops the fill but keeps the rail. |
| data-range | When `range` is set | Marks a multi-thumb slider (two or more handles) so the recipe can style the fill as a band between the outermost handles. |
| data-disabled | When disabled (own prop or inherited from a surrounding `Field`) | Mutes the fill and blocks every interaction. |
| data-readonly | When read-only (own prop or inherited from a surrounding `Field`) | Renders the value while blocking value-changing interaction. |
| data-invalid | When invalid (own prop or inherited from a surrounding `Field`) | Applies the invalid treatment; each thumb also exposes `aria-invalid`. |
| data-required | When required (own prop or inherited from a surrounding `Field`) | Marks the control as required; each thumb also exposes `aria-required`. |
| data-thumb | On each thumb of a range slider | `min` on the first handle and `max` on the last. A handle between them is neither end, so it carries no `data-thumb` rather than a misleading one. |
| data-dragging | On the thumb the pointer currently controls | Reveals the value tooltip and suppresses the position transition so the handle tracks the pointer exactly. |
| data-focus | On the focused thumb | Draws the focus ring and reveals the value tooltip for keyboard users. |
| role="slider" | On every thumb | The thumb is the accessibility owner: it carries `aria-valuenow` / `aria-valuemin` / `aria-valuemax` and the keyboard surface. |
| role="group" | When `range` is set | Ties the two `role="slider"` thumbs together under the surrounding `Field` label. |
### Slider.Track {#slider-track}
#### Data attributes {#slider-track-data-attributes}
| Attribute | Applied when | Purpose |
| ----------------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
| data-orientation | Inherited from the root (descendant selector) | A vertical rail flips its long axis; the track reads the root’s `data-orientation` rather than carrying its own. |
### Slider.Range {#slider-range}
#### Data attributes {#slider-range-data-attributes}
| Attribute | Applied when | Purpose |
| ----------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
| data-track | Inherited from the root (descendant selector) | The `inverted` / `none` fill mode is read from the root’s `data-track`; the band recolours or hides itself accordingly. Its offset and length are written inline (a continuous value is not a `data-*` hook). |
### Slider.Thumb {#slider-thumb}
#### Props {#slider-thumb-props}
| Name | Type | Default | Description |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| index | `number` | 0 | Which value this thumb controls. The default anatomy renders index `0` (and `1` for a range); pass it explicitly only when composing the thumbs by hand. |
| disabled | `boolean` | false | Disables just this handle — it cannot be moved and is skipped as a drag target, while the other thumbs stay interactive. A neighbour dragged into a disabled handle stops against it. The slider’s own `disabled` still disables every thumb. |
| children | `React.ReactNode \| ((state: SliderThumbRenderProps) => React.ReactNode)` | - | Content of the value bubble. When omitted, the formatted value renders. A plain node replaces it with static content; a function receives this thumb’s `value` / `formatted` / `index` / `isDragging` / `isFocused`. Either form swaps only what the bubble shows — the handle and bubble chrome stay the thumb’s. |
| classNames | `Partial>` | - | Per-slot class name overrides. |
| slotProps | `Partial>>` | - | Per-slot HTML attribute overrides. |
| className | `string` | - | Appends custom classes to the root slot of this part. |
#### Data attributes {#slider-thumb-data-attributes}
| Attribute | Applied when | Purpose |
| -------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
| data-slot="tooltip" | Always | The value bubble parented to the handle; style or override it via `classNames.tooltip` / `slotProps.tooltip`. |
| data-slot="arrow" | Always | The bubble’s pointer, a real element (not a pseudo-element) so `classNames.arrow` / `slotProps.arrow` can resize or recolour it. |
| data-thumb | On the first / last handle of a range | `min` on the first handle and `max` on the last; a middle handle carries none. |
| data-dragging | While the pointer controls this handle | Reveals the value bubble and suppresses the position transition so the handle tracks the pointer exactly. |
| data-focus | While this handle holds keyboard focus | Draws the focus ring and reveals the value bubble for keyboard users. |
| data-disabled | When this handle is disabled (own prop or the whole slider) | Mutes just this handle and hides its value bubble. |
| role="slider" | Always | The handle is the accessibility owner: it carries `aria-valuenow` / `aria-valuemin` / `aria-valuemax` and the keyboard surface. |
### Slider.Ticks {#slider-ticks}
#### Data attributes {#slider-ticks-data-attributes}
| Attribute | Applied when | Purpose |
| ----------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
| data-slot="tick" | On each step mark | One mark of the grid; style or override it via `classNames.tick` / `slotProps.tick`. Positions are written inline. Rendered `aria-hidden` (decorative). |
### Slider.Value {#slider-value}
#### Data attributes {#slider-value-data-attributes}
| Attribute | Applied when | Purpose |
| ----------------------------------------------- | ------------ | ----------------------------------------------------- |
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
### Type Definitions {#slider-type-definitions}
| Name | Definition |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| SliderOrientation | `'horizontal' \| 'vertical'` |
| SliderSize | `'small' \| 'base' \| 'large'` |
| SliderVariant | `'primary' \| 'info' \| 'success' \| 'danger' \| 'warning'` |
| SliderTrackMode | `'normal' \| 'inverted' \| 'none'` |
| SliderTooltip | `'auto' \| 'always' \| 'never'` |
| SliderThumbRenderProps | `{ value: number; formatted: string; index: number; isDragging: boolean; isFocused: boolean }` |
| SliderThumbSlot | `'root' \| 'tooltip' \| 'arrow'` |
| SliderTicksSlot | `'root' \| 'tick'` |
| SliderValueRenderProps | `{ values: number[]; formatted: string[]; range: boolean }` |
## When to use
Any bounded numeric selection where dragging beats typing — volume, brightness, temperature, zoom, a price/date range filter, gradient stops. Wrap it in `Field` to attach a label, description, or error, and to cascade `disabled` / `readOnly` / `invalid` / `required`. Not this — use `takeoff-input` (`type="number"`) for exact entry, `takeoff-progress` for a non-interactive completion bar.
## Accessibility
- Each `Slider.Thumb` is the a11y owner: `role="slider"` carrying
`aria-valuenow` / `aria-valuemin` / `aria-valuemax`, plus the keyboard
surface. A `range` root adds `role="group"` to tie the thumbs together under
the `Field` label.
- Compose inside `Field` so `Field.Label` / `Field.Description` /
`Field.ErrorMessage` wire via shared IDs; without a visible label, pass
`aria-label` on the thumb. `formatValue` also feeds `aria-valuetext`.
- Disabled slider leaves the tab order; read-only stays focusable but does not
change value. In a range each thumb is bounded by its neighbour, so the
keyboard can never push one past the other.
| Key | Action |
| ----------- | -------------------------------------------- |
| `←` `↓` | Decrease the focused thumb by one `step` |
| `→` `↑` | Increase the focused thumb by one `step` |
| `Page Down` | Decrease by ten steps |
| `Page Up` | Increase by ten steps |
| `Home` | Jump to the lowest value the thumb may take |
| `End` | Jump to the highest value the thumb may take |
---
# Stepper
`Stepper` guides users through a multi-step flow. Each step renders an indicator
(status dot, status glyph, or custom content), an optional connecting rail, and
a title with an optional description. The active step is index-based and can be
controlled or uncontrolled.
Steps are real `` elements: keyboard users activate them with `Enter` or
`Space`, arrow keys (plus `Home`/`End`) move focus along the list, and the
active step is announced through `aria-current="step"`.
## Usage
```tsx
import { Stepper } from '@takeoff-ui/react-spar';
```
```tsx
```
## Playground
```tsx
function PlaygroundDemo() {
const [active, setActive] = React.useState(1);
return (
Flight
Choose your route
Passengers
Traveler details
Payment
Card or miles
setActive(active - 1)}>
Back
setActive(active + 1)}>
Next
);
}
render(
i}>
Custom
Error
Disabled
Active
Inactive
);
}
render(
{steps.map((step, index) => (
status === 'completed' ? undefined : {index + 1}
}
>
{step}
))}
);
}
render(
Account
Only the next step is clickable
Verification
Done
);
}
render(
Available
Locked
Visible but skipped
Available
);
}
render(
Origin
Start city
Seats
Selected cabin
Boarding
Final details
);
}
render(
Order placed
We received your order
Processing
Tickets are being issued
Ready
Check your inbox
);
}
render(
Cabin
Seats
Extras
);
}
render(
{['xsmall', 'small', 'base', 'large'].map(size => (
{size}
Active
Next
))}
);
}
render(` trigger, so steps are focusable and keyboard-activatable by
default.
- The active step's trigger carries `aria-current="step"`.
- Steps that cannot change the active step (non-clickable or blocked by
`linear`) expose `aria-disabled` and stay silent on press; `disabled` steps
are natively disabled and removed from the tab order.
- Indicators and rails are decorative and hidden from assistive technology; a
step's accessible name comes from its title text, extended with a visually
hidden status suffix on completed/errored steps — localize it through the
root's `completedLabel`/`errorLabel` props.
- `Stepper.Description` is linked to the trigger through `aria-describedby`
instead of inflating the accessible name.
- Arrow keys along the stepper's orientation move focus between step triggers;
`Home` and `End` jump to the first and last focusable step.
## API Reference
### Stepper {#stepper}
#### Props {#stepper-props}
| Name | Type | Default | Description |
| ----------------------------------- | ----------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| children | `React.ReactNode` | - | `Stepper.Item` elements. The root derives each step’s index from its position in `children`. |
| active | `number` | - | Currently active step index (controlled). Not clamped: an out-of-range index renders every step completed (or inactive) with no active step. |
| defaultActive | `number` | 0 | Initially active step index (uncontrolled). |
| orientation | `StepperOrientation` | 'horizontal' | Layout axis of the step list. |
| mode | `StepperMode` | 'default' | Display mode — indicators with connecting rails (`'default'`) or a progress border per step without rails (`'compact'`). |
| linear | `boolean` | false | Restricts navigation to a linear progression: any previous step, or the next step when the current one is neither errored nor disabled. |
| size | `StepperSize` | 'base' | Density scale for indicators and typography. |
| reverse | `boolean` | false | Flips indicators and content along the cross axis. |
| completedLabel | `string` | 'completed' | Accessible status suffix appended to a completed step's name — the check glyph alone is invisible to assistive technology. Localize per stepper; an empty string drops the suffix. |
| errorLabel | `string` | 'error' | Accessible status suffix appended to an errored step's name — the error glyph alone is invisible to assistive technology. Localize per stepper; an empty string drops the suffix. |
| classNames | `Partial>` | - | Per-slot class name overrides. |
| slotProps | `Partial>>` | - | Per-slot HTML attribute overrides. |
| className | `string` | - | Appends custom classes to the root slot of this part. |
#### Events {#stepper-events}
| Name | Type | Default | Description |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| onActiveChange | `(index: number) => void` | - | Fires with the new step index when the active step changes. |
| onStepClick | `(detail: StepperStepClickDetail) => void` | - | Fires on selectable step presses, and on the active step when pressed again, with the step's index and progress status. Disabled, non-clickable, and linear-blocked steps emit nothing. |
#### Data attributes {#stepper-data-attributes}
| Attribute | Applied when | Purpose |
| ----------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------- |
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
| data-orientation | Always | Reflects the resolved `orientation` prop (`horizontal` \| `vertical`). Emitted by the wrapper. |
| data-mode | Always | Reflects the resolved `mode` prop (`default` \| `compact`). |
| data-size | Always | Reflects the resolved `size` prop so theme recipes can scope size variants. |
| data-linear | When `linear` is true. | Marks linear progression; selection gating itself is wrapper-owned. |
| data-reverse | When `reverse` is true. | Styling hook for the flipped indicator/content layout. |
### Stepper.Item {#stepper-item}
#### Props {#stepper-item-props}
| Name | Type | Default | Description |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| children | `React.ReactNode` | - | Step content — typically `Stepper.Title` and `Stepper.Description`. Renders inside the step’s `` trigger and provides its accessible name. |
| error | `boolean` | - | Marks the step as errored without changing its progress status. |
| disabled | `boolean` | - | Disables the step. The trigger renders as a natively disabled button: unfocusable, unselectable, and silent. |
| isClickable | `boolean` | true | Whether the step can be activated by pressing it. Non-clickable steps stay visible in the flow but are removed from the tab order. |
| indicator | `React.ReactNode \| ((state: StepperIndicatorState) => React.ReactNode)` | - | Custom indicator content. Replaces the built-in status glyph (check, close, or dot) for every status except `disabled`. Pass a function to render by status — returning `undefined` or `null` falls back to the built-in glyphs, so numbered steps can surface the check once completed. |
| classNames | `Partial>` | - | Per-slot class name overrides. |
| slotProps | `Partial>>` | - | Per-slot HTML attribute overrides. |
| className | `string` | - | Appends custom classes to the root slot of this part. |
#### Data attributes {#stepper-item-data-attributes}
| Attribute | Applied when | Purpose |
| ----------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
| data-state | Always | Resolved progress status: `inactive` \| `active` \| `completed`. |
| data-error | When `error` is true. | Error treatment modifier; can coexist with any progress status. |
| data-disabled | When `disabled` is true. | Disabled treatment modifier; the trigger is natively disabled. |
| data-clickable | When pressing the step may change the active step — never on the active step itself. | Cursor/hover affordance hook. Respects `disabled`, `isClickable`, and linear gating. |
### Stepper.Title {#stepper-title}
#### Data attributes {#stepper-title-data-attributes}
| Attribute | Applied when | Purpose |
| ----------------------------------------------- | ------------ | ----------------------------------------------------- |
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
### Stepper.Description {#stepper-description}
#### Data attributes {#stepper-description-data-attributes}
| Attribute | Applied when | Purpose |
| ----------------------------------------------- | ------------ | ----------------------------------------------------- |
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
### Type Definitions {#stepper-type-definitions}
| Name | Definition |
| ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| StepperOrientation | `'horizontal' \| 'vertical'` |
| StepperMode | `'default' \| 'compact'` |
| StepperSize | `'large' \| 'base' \| 'small' \| 'xsmall'` |
| StepperStepClickDetail | `{ index: number; status: StepperStepStatus }` |
| StepperIndicatorState | `{ status: StepperStepStatus; index: number }` |
| StepperItemSlot | `'root' \| 'trigger' \| 'rail' \| 'indicator' \| 'content'` |
## When to use
Multi-step flows where the sequence itself is meaningful and the user should see where they are and what remains — checkout, booking, onboarding, multi-page forms. Not this — use `takeoff-tabs` when sections can be visited in any order, and `takeoff-progress` when you only need to show completion without naming the steps.
---
# Toast
`Toast` displays transient feedback without interrupting the current workflow.
The queue, timers, pause/resume behavior, hotkey focus, and live-region
semantics come from Spar's headless toast controller; React Spar renders each
item with Takeoff Alert anatomy by default.
Use variants to show the visual tone of the toast.
## Usage
```tsx
import { Toaster, createToaster } from '@takeoff-ui/react-spar';
```
```tsx
const toaster = createToaster({ placement: 'bottom-end' });
function App() {
return (
<>
toaster.success({
title: 'Booking saved',
description: 'Passenger details were updated successfully.',
})
}
>
Save
Save booking
);
}
render(
notify('default', 'Neutral')} variant="neutral">Neutral
notify('success', 'Success')} variant="success">Success
notify('info', 'Info')} variant="info">Info
notify('warning', 'Warning')} variant="warning">Warning
notify('error', 'Danger')} variant="danger">Danger
);
}
render(
notify(filled, 'Filled')}>Filled
notify(filledLight, 'Filled light')}>Filled light
notify(outlined, 'Outlined')}>Outlined
notify(gradient, 'Gradient')}>Gradient
);
}
render(
{placements.map(([placement, controller]) => (
showToast(placement, controller)}>
{placement}
))}
{placements.map(([placement, controller]) => (
);
}
render(
Show persistent
toaster.dismiss()}>Dismiss all
);
}
render(
Create
Update
);
}
render(
Save async
);
}
render(
Show toast
);
}
render(
showToast('Max 1', oneToaster)}>Max 1
showToast('Max 5', fiveToaster)}>Max 5
showToast('Max 8', eightToaster)}>Max 8
);
}
render(
threeSecondToaster.info({
title: '3 seconds',
description: 'This toast closes first.',
})
}
>
3s
fiveSecondToaster.info({
title: '5 seconds',
description: 'This toast stays a bit longer.',
})
}
>
5s
eightSecondToaster.info({
title: '8 seconds',
description: 'This toast stays visible the longest.',
})
}
>
8s
);
}
render(
Show timed toast
{seconds}s
);
}
render(
Show toast
Close from outside
);
}
render(
Show custom toast
{(toast) => {
const details = toast.data || {};
return (
Boarding pass
{toast.title}
{toast.description}
toaster.dismiss(toast.id)}
>
Dismiss
Gate
{details.gate}
Group
{details.group}
Time
{details.time}
);
}}
);
}
render(>` | - | |
| slotProps | `Partial>>` | - | |
| label | `string` | 'Notifications (F8)' | Accessible label for the toast viewport region. |
| hotkey | `string[]` | ['F8'] | Keyboard shortcut that focuses the toast viewport. |
| className | `string` | - | Appends custom classes to the root slot of this part. |
#### Data attributes {#toaster-data-attributes}
| Attribute | Applied when | Purpose |
| ----------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------- |
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
| data-placement | Always | Reflects the toaster placement for viewport positioning. |
| data-overlap | When `overlap` is true | Enables the overlapped visual stack recipe. |
| data-expanded | When an overlapping toaster is hovered or focused | Indicates that the overlapped stack is expanded for interaction. |
### Toast {#toast}
#### Props {#toast-props}
| Name | Type | Default | Description |
| ------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------- |
| toast | `ToastData` | - | Toast item supplied by the headless toaster controller. |
| children | `React.ReactNode` | - | Optional custom toast content. When omitted, Toast renders the Takeoff Alert anatomy. |
| toaster | `ToasterController` | - | Controller used to pause, resume, and dismiss the toast. |
| appearance | `ToastAppearance` | 'filled' | Alert appearance used by the default toast renderer. |
| closeLabel | `string` | 'Dismiss notification' | Accessible label for the default close control. |
| classNames | `Partial>` | - | |
| slotProps | `Partial>>` | - | |
| className | `string` | - | Appends custom classes to the root slot of this part. |
#### Data attributes {#toast-data-attributes}
| Attribute | Applied when | Purpose |
| ----------------------------------------------- | ------------ | -------------------------------------------------------- |
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
| data-toast-id | Always | Stable toast item identifier used for layout motion. |
| data-status | Always | Reflects the toast lifecycle status. |
| data-type | Always | Reflects the headless toast type used for styling hooks. |
### Type Definitions {#toaster-type-definitions}
| Name | Definition |
| ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ToasterController | `{ placement: ToastPlacement; maxVisibleToasts: number; create: (options: ToastOptions) => string; success: (options: ToastOptions) => string; error: (options: ToastOptions) => string; warning: (options: ToastOptions) => string; info: (options: ToastOptions) => string; loading: (options: ToastOptions) => string; update: (id: string, options: ToastUpdateOptions) => void; dismiss: (id?: string) => void; pause: (id?: string) => void; resume: (id?: string) => void; clear: () => void; destroy: () => void; promise: (promise: Promise, options: ToastPromiseOptions) => Promise; subscribe: (listener: () => void) => () => void; getSnapshot: () => ToastData[] }` |
| ToastAppearance | `'filled' \| 'filledLight' \| 'outlined' \| 'gradient'` |
| ToastData | `{ id: string; title?: ReactNode; description?: ReactNode; type: ToastType; duration: number \| null; createdAt: number; remaining: number \| null; status: ToastStatus; announcement: ToastAnnouncement; action?: ToastActionOptions \| undefined; dismissible: boolean; data?: unknown }` |
### Controller Values
| Option | Default | Behavior |
| ------------------ | -------------- | ------------------------------------------------------------------------------------------------------------ |
| `placement` | `'bottom-end'` | Reflected on `data-placement` for viewport positioning. |
| `duration` | `5000` | Auto-dismiss duration for ordinary toasts. |
| `maxVisibleToasts` | `24` | Maximum number of toasts to display at once. Extra items stay queued; lower this for denser product screens. |
| `removeDelay` | `200` | Time a dismissing toast remains mounted for exit motion. |
| `pauseOnPageIdle` | `false` | Timers continue unless this option is enabled. |
## When to use
Any ephemeral, auto-dismissing notification fired imperatively (success/error/info/warning/loading, promise results, undo actions). Not for persistent inline status banners on the page — for those use an Alert component instead.
## Accessibility
- The viewport is an `aria-live` region; toasts are announced without stealing
focus.
- Press the `hotkey` (default `F8`) to move focus into the toast viewport;
`label` names that region.
- Each toast's default close control is labelled by `closeLabel`.
- Timers pause on hover/focus (and on page idle when `pauseOnPageIdle` is
enabled), giving users time to read and act.
---
# Upload
`Upload` is a compound, composition-first file control. The root owns the value
and validation; the dropzone, trigger, list, and per-file actions are parts you
compose — the parts you place are the parts you get.
It never uploads — no part of it does, `Upload.Submit` included. The transfer is
yours: start it from `onFileAccept` as files are accepted, or from
`Upload.Submit`'s `onClick` when the user sends the batch.
## Playground
```tsx
function PlaygroundDemo() {
const [files, setFiles] = React.useState([]);
const [error, setError] = React.useState('');
return (
Attachments
{ setFiles(next); setError(''); }}
onFilesReject={(rejections) => setError(rejections[0].file.name + ' was not accepted.')}
>
Choose a file or drag & drop it here.
Choose File
{error
? {error}
: Images or PDF, up to 5 MB each. }
);
}
render(
Choose a folder — every file inside it comes along.
Choose Folder
{/* The path is what the folder pick adds, so the row shows it in place of the bare name. */}
{(items) => items.map((item) => (
{item.file?.webkitRelativePath || item.name}
))}
);
}
render(
);
}
render(
Choose a file to upload and scan it.
Choose File
);
}
render(
{file.name} — {file.error}
retry(file)}>
Try again
```
Every word the component renders on its own comes from a root prop, one per
string — the same shape as `Stepper`'s `completedLabel` / `errorLabel` or
`Alert`'s `closeLabel`:
| Prop | Default | Where it shows |
| ----------------- | ------------------------ | --------------------------------------------------- |
| `uploadingLabel` | `Uploading…` | row support text while `uploading` |
| `processingLabel` | `Processing…` | row support text while `processing` |
| `completedLabel` | `Completed` | row support text on `completed` |
| `errorLabel` | `Failed` | row support text on `error` with no `error` message |
| `progressLabel` | `{name} upload progress` | the progress bar's accessible name |
| `downloadLabel` | `Download {name}` | `action="download"` accessible name |
| `removeLabel` | `Remove {name}` | `action="remove"` accessible name |
The first four name the state alone — the row already shows the file and that it
is an upload. The last three take a `{name}` placeholder so a translation can
move the file name inside the sentence
(`removeLabel="{name} dosyasını kaldır"`), which concatenating a verb and a name
cannot do. An entry's own `error` beats `errorLabel`; an action's own `label`
beats `downloadLabel` / `removeLabel`.
A label that resolves to nothing (`''`, or an `undefined` out of a partial
dictionary) is read differently by half: a blank status label drops the support
line, glyph included, while a blank `progressLabel` / `downloadLabel` /
`removeLabel` is ignored and the default stands — those exist only as accessible
names, and an icon-only control cannot go unnamed.
A localized app sets them once through the provider's `components` map rather
than at every call site:
```tsx
```
The file size is not in here. It is a number, so `Intl` writes it in the
runtime's locale — the unit and the decimal mark both (`1.5 MB` in English,
`1,5 MB` in Turkish).
## Sending the batch
`onFileAccept` sends each file the moment it is accepted. `Upload.Submit` is the
other model: the value fills up, the user reads the list back, and one press
sends what is in it. Nothing about the part performs the upload — it is a
`Button` that knows when sending makes sense, and disables itself when it does
not: while the value is empty, and while a batch is already going (any file
`uploading` or `processing`). The second is the double-submit the status
vocabulary makes visible — press again mid-transfer and the same files go twice
— so the part reads the status rather than asking you to wire
`disabled={inFlight}` yourself. The transfer is still yours; only the guard is
not.
Its place is beside the Trigger, in the zone: browse and send are one decision,
so they belong on one line. The zone stacks its children, so wrap the two in
`Upload.Actions` — a row that holds whatever you put in it, `8px` apart rather
than on the zone's own looser rhythm. It is a layout box and nothing else, so a
third control or a file count goes in it just as well, and a zone holding only a
Trigger needs none of it.
```tsx
function SubmitDemo() {
const [files, setFiles] = React.useState([]);
const patch = (id, next) =>
setFiles((current) => current.map((entry) => (entry.id === id ? { ...entry, ...next } : entry)));
// Nothing has moved before this runs — which is the whole difference from the
// onFileAccept demo above, where choosing a file was the same as sending it.
const send = () => files.forEach((entry) => {
let percent = 0;
const transfer = window.setInterval(() => {
percent += 25;
if (percent < 100) return patch(entry.id, { status: 'uploading', progress: percent });
window.clearInterval(transfer);
patch(entry.id, { status: 'completed', progress: undefined });
}, 300);
});
const inFlight = files.some((entry) => entry.status === 'uploading');
return (
Attach what you need — nothing is sent until you say so.
{/* No disabled guard here: Submit takes itself down while the value is
empty and again while a batch is in flight. The label is the part
that is yours — the component knows when sending is off, not what to
call it. */}
Choose Files
{inFlight ? 'Sending…' : 'Send'}
);
}
render(
```
All three kinds in one row below — a `"preview"` of your own beside the two that
arrive wired, and a remove that asks first. The veto is what makes that last one
possible, and it is synchronous: the built-in reads `defaultPrevented` as soon
as your handler returns, so a confirmation that resolves later has already
missed its chance to stop the removal.
```tsx
function ActionsDemo() {
const [files, setFiles] = React.useState([
{ id: '1', name: 'cover-photo.jpg', size: 840000, type: 'image/jpeg', url: '/img/takeoff-og.jpg' },
{ id: '2', name: 'brand-mark.svg', size: 12000, type: 'image/svg+xml', url: '/img/brand-mark.svg' },
]);
return (
{(items) => items.map((item) => (
// Bare actions: the shorthand, so the three below replace the default
// download + remove pair — order included.
{/* A name of its own: the verb comes from label, the glyph from
children, the behavior from onClick. */}
window.open(item.url, '_blank', 'noopener')}
>
{/* Built-in: saves the file, needs no wiring. */}
{
if (!window.confirm('Remove ' + item.name + '?')) event.preventDefault();
}}
/>
))}
);
}
render(
);
}
render(` is the whole story.
The demo sets them on the `Field` rather than on the `Upload`, which is how a
form usually reaches them:
```tsx
const STATES = ['default', 'disabled', 'readOnly', 'invalid'];
function StatesDemo() {
const [state, setState] = React.useState('default');
const [files, setFiles] = React.useState([
// Both preloaded and both downloadable, so the only thing that changes
// between the states below is the state itself.
{ id: '1', name: 'cover-photo.jpg', size: 840000, type: 'image/jpeg', url: '/img/takeoff-og.jpg' },
{ id: '2', name: 'brand-mark.svg', size: 12000, type: 'image/svg+xml', url: '/img/brand-mark.svg' },
]);
return (
{STATES.map((name) => (
setState(name)}
>
{name}
))}
{/* Set on the Field, not on the Upload: all three resolve as
own prop ?? Field ?? false, and the Field is the usual source. */}
Attachments
Choose a file or drop it here.
Choose File
{state === 'invalid'
? At least one attachment has to be a PDF.
: Watch the trigger, the remove action, and the zone. }
);
}
render(`s.
Icon-only actions carry a file-specific `aria-label` ("Remove report.pdf").
- Inside a `Field`, the root is the labelled region (`role="group"`), named by
`Field.Label` and described by `Field.Description` / `Field.ErrorMessage`.
Your own ARIA always wins.
- The native file input is visually hidden but reachable through the trigger.
- Removing a row moves focus before the row unmounts: to the next row's matching
action, or to the row above when the last one goes, or to `Upload.Trigger`
when the list empties. An unmounted control would otherwise hand focus back to
the document body, restarting every subsequent `Tab` from the top of the page.
- Parts rendered through `as` stay operable from the keyboard — `Enter` and
`Space` run the same built-in behavior a click does — and an `as="a"` trigger
or action is announced as a link while it has an `href` to follow.
## API Reference
### Upload {#upload}
#### Props {#upload-props}
| Name | Type | Default | Description |
| ------------------------------------ | ----------------------------------------------------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| value | `UploadFile[]` | - | Committed files (controlled). Pair with `onValueChange`. |
| defaultValue | `UploadFile[]` | - | Initial files for uncontrolled usage. |
| accept | `string` | - | Acceptable file types — comma-separated MIME types (`image/*`) and/or extensions (`.pdf`). |
| multiple | `boolean` | false | Allow selecting/holding more than one file. When `false`, a new selection replaces the current file. |
| directory | `boolean` | false | Browse folders instead of single files: the picker takes a directory and every file inside it (recursively), each keeping its `webkitRelativePath` (e.g. `reports/2024/q1.pdf`) for rebuilding the tree. Implies `multiple`. Only affects the picker — dropping a folder on `Upload.Dropzone` does not expand it. |
| maxFileSize | `number` | - | Maximum size per file, in bytes. Larger files are rejected. |
| maxFileCount | `number` | - | Maximum number of files (only meaningful with `multiple`). Extra files are rejected. |
| uploadingLabel | `string` | 'Uploading…' | Row support text while a file transfers. Localize per upload; an empty string drops the status line, glyph included. |
| processingLabel | `string` | 'Processing…' | Row support text while the server works on a file that has landed. Localize per upload; an empty string drops the status line, glyph included. |
| completedLabel | `string` | 'Completed' | Row support text once a file is done. Localize per upload; an empty string drops the status line, glyph included. |
| errorLabel | `string` | 'Failed' | Row support text for a failure that reports no `error` message of its own — an entry's own `error` always wins. Localize per upload; an empty string drops the status line, glyph included. |
| progressLabel | `string` | '{name} upload progress' | Accessible name for a row's progress bar, as a template: `{name}` stands for the file's name, so several bars uploading at once stay distinguishable. An empty string counts as unset — the bar cannot go unnamed. |
| downloadLabel | `string` | 'Download {name}' | Accessible name for the built-in `action="download"`, as a `{name}` template. An `Upload.ItemAction`'s own `label` wins over it, and an empty string counts as unset — an icon-only button cannot go unnamed. |
| removeLabel | `string` | 'Remove {name}' | Accessible name for the built-in `action="remove"`, as a `{name}` template. An `Upload.ItemAction`'s own `label` wins over it, and an empty string counts as unset — an icon-only button cannot go unnamed. |
| disabled | `boolean` | - | Disables the whole control. Also inherited from a surrounding `Field`. |
| readOnly | `boolean` | - | Read-only: files render and remain downloadable, but adding/removing is blocked. Also inherited from `Field`. |
| invalid | `boolean` | - | Marks the control invalid — mirrored as `data-invalid` for the recipe's danger styling. Also inherited from `Field`. |
| classNames | `Partial>` | - | Per-slot class name overrides. |
| slotProps | `Partial>>` | - | Per-slot HTML attribute overrides. |
| className | `string` | - | Appends custom classes to the root slot. |
#### Events {#upload-events}
| Name | Type | Default | Description |
| ---------------------------------- | ------------------------------------------------------------------------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| onValueChange | `(files: UploadFile[]) => void` | - | Called with the next file array after a selection, drop, or removal. |
| onFileAccept | `(files: UploadFile[]) => void` | - | Called with the entries that just entered the value — the files wrapped this batch rather than the whole array, which is what a consumer starts its own upload from. Files dropped as duplicates of ones already held are not reported. |
| onFilesReject | `(rejections: UploadRejection[]) => void` | - | Called with every file rejected by validation (type, size, or count). |
#### Data attributes {#upload-data-attributes}
| Attribute | Applied when | Purpose |
| ----------------------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------- |
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
| data-disabled | When disabled (own prop or inherited from a surrounding `Field`) | Styling hook for the disabled state. |
| data-readonly | When read-only (own prop or `Field`) | Styling hook for the read-only state — takes the zone out of the drag flow. |
| data-invalid | When invalid (own prop or `Field`) | Styling hook for the invalid state (danger treatment). |
### Upload.Dropzone {#upload-dropzone}
#### Data attributes {#upload-dropzone-data-attributes}
| Attribute | Applied when | Purpose |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
| data-drag-state | While a payload is dragged over (`accept` \| `reject`, by matching the dragged type against `accept`) | Styling hook distinguishing an acceptable from a rejected drag. Unstyled by default — the recipe ships no drag treatment. |
### Upload.Actions {#upload-actions}
#### Data attributes {#upload-actions-data-attributes}
| Attribute | Applied when | Purpose |
| ----------------------------------------------- | ------------ | ----------------------------------------------------- |
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
### Upload.Trigger {#upload-trigger}
#### Props {#upload-trigger-props}
| Name | Type | Default | Description |
| ------------------------------- | ----------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| children | `React.ReactNode` | - | Trigger label (e.g. "Choose file"). |
| appearance | `ButtonAppearance` | 'outlined' | Button appearance. Quieter than Button's own default, and the treatment `Upload.Submit` takes too — the two stand beside each other in the zone, so they read as one pair. Re-point it on a Trigger that stands alone. |
| variant | `ButtonVariant` | 'neutral' | Button color variant. |
| classNames | `Partial>` | - | |
| slotProps | `Partial>>` | - | |
| className | `string` | - | Appends custom classes to the root slot. |
#### Data attributes {#upload-trigger-data-attributes}
| Attribute | Applied when | Purpose |
| ----------------------------------------------- | ------------ | ----------------------------------------------------- |
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
### Upload.Submit {#upload-submit}
#### Props {#upload-submit-props}
| Name | Type | Default | Description |
| ------------------------------- | ----------------------------------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| children | `React.ReactNode` | - | Submit label (e.g. "Upload"). Wire the actual upload through `onClick`. |
| appearance | `ButtonAppearance` | 'outlined' | Button appearance. The Trigger's, not Button's own: the two stand beside each other in the zone, so they read as one pair rather than as two weights. Re-point it where the send is the page's primary action. |
| variant | `ButtonVariant` | 'neutral' | Button color variant. |
| classNames | `Partial>` | - | |
| slotProps | `Partial>>` | - | |
| className | `string` | - | Appends custom classes to the root slot. |
#### Data attributes {#upload-submit-data-attributes}
| Attribute | Applied when | Purpose |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
| data-disabled | While the value is empty, while any file is `uploading` or `processing`, or when the root (or the part) is disabled | Emitted by the underlying Button. The in-flight case is the double-submit guard — pressing again mid-transfer would send the same files twice — so it is the part's own, not something to wire through `disabled`. |
### Upload.List {#upload-list}
#### Data attributes {#upload-list-data-attributes}
| Attribute | Applied when | Purpose |
| ----------------------------------------------- | ------------ | ----------------------------------------------------- |
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
### Upload.Item {#upload-item}
#### Props {#upload-item-props}
| Name | Type | Default | Description |
| ------------------------------- | ----------------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| file | `UploadFile` | - | The file this row renders. Also what its `Upload.ItemAction` children read. |
| children | `React.ReactNode` | - | Per-file action controls (`Upload.ItemAction`), wrapped in a default `Upload.ItemActions` — and replacing its default download + remove pair rather than joining it. A composed `Upload.ItemPreview`, `Upload.ItemContent`, or `Upload.ItemActions` among them is hoisted into its own region, replacing that default. |
| classNames | `Partial>` | - | |
| slotProps | `Partial>>` | - | |
| className | `string` | - | Appends custom classes to the root slot. |
#### Data attributes {#upload-item-data-attributes}
| Attribute | Applied when | Purpose |
| ----------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------- |
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
| data-status | Always (`idle` \| `uploading` \| `processing` \| `completed` \| `error`) | Per-file status styling hook (consumer-driven `UploadFile.status`). |
### Upload.ItemContent {#upload-item-content}
#### Data attributes {#upload-item-content-data-attributes}
| Attribute | Applied when | Purpose |
| ----------------------------------------------- | ------------ | ----------------------------------------------------- |
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
### Upload.ItemPreview {#upload-item-preview}
#### Data attributes {#upload-item-preview-data-attributes}
| Attribute | Applied when | Purpose |
| ----------------------------------------------- | ------------ | ----------------------------------------------------- |
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
### Upload.ItemActions {#upload-item-actions}
#### Data attributes {#upload-item-actions-data-attributes}
| Attribute | Applied when | Purpose |
| ----------------------------------------------- | ------------ | ----------------------------------------------------- |
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
### Upload.ItemAction {#upload-item-action}
#### Props {#upload-item-action-props}
| Name | Type | Default | Description |
| ------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| action | `"download" \| "remove" \| (string & {})` | - | Names the action, mirrored as `data-action` whatever the name is. Two names arrive wired, each with its own icon and label: `'download'` saves the row's file (its `File` through an object URL, a preloaded entry through its `url`) and stays available in read-only; `'remove'` drops the file from `value` and is not rendered at all in read-only. Any other name — `'preview'`, `'retry'`, `'share'` — is yours: the behavior comes from `onClick`, the glyph from `children`, the wording from `label`. |
| label | `string` | the root's copy for the `action` (`downloadLabel` / `removeLabel`) | Accessible name for the action, as a template: `{name}` stands for the file's name, so `"Preview {name}"` gives `aria-label="Preview report.pdf"` and icon-only actions stay labelled per file. An explicit `aria-label` wins over it, and an empty one counts as unset, so a built-in action falls back to the root's copy rather than losing its name. |
| children | `React.ReactNode` | - | Action content — typically an icon. Defaults to the `action`'s own glyph. |
| appearance | `ButtonAppearance` | 'outlined' | Button appearance. Defaults to the row's shape — a small, quiet icon button beside the file's details — rather than Button's own default, so a text-only remove or a danger-coloured one is a re-point, not a rebuild. |
| variant | `ButtonVariant` | 'neutral' | Button color variant. |
| size | `ButtonSize` | 'small' | Button size scale. |
| classNames | `Partial>` | - | |
| slotProps | `Partial>>` | - | |
| className | `string` | - | Appends custom classes to the root slot. |
#### Data attributes {#upload-item-action-data-attributes}
| Attribute | Applied when | Purpose |
| ----------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------ |
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
| data-action | When `action` is set (any name; `download` \| `remove` are the wired pair) | Names the action, for styling one action out of a row. |
### Type Definitions {#upload-type-definitions}
| Name | Definition |
| ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| UploadFile | `{ id: string; file?: File; name?: string; size?: number; type?: string; url?: string; thumbUrl?: string; status?: UploadFileStatus; progress?: number; error?: string }` |
| UploadRejection | `\| { file: File; code: 'file-invalid-type'; /** The `accept` list the file failed to match. \*/ accept: string; } \| { file: File; code: 'file-too-large'; /** The `maxFileSize` (bytes) the file exceeded. _/ maxFileSize: number; } \| { file: File; code: 'too-many-files'; /\*\* How many files were allowed — `maxFileCount`, or 1 without `multiple`. _/ maxFileCount: number; }` |
| ButtonAppearance | `'filled' \| 'filledLight' \| 'outlined' \| 'text'` |
| ButtonVariant | `'primary' \| 'secondary' \| 'neutral' \| 'info' \| 'success' \| 'danger' \| 'warning' \| 'white' \| 'black'` |
| UploadItemContentSlot | `'root' \| 'name' \| 'size' \| 'status' \| 'progress'` |
| UploadItemPreviewSlot | `'root' \| 'image' \| 'icon' \| 'extension'` |
| UploadItemPreviewSlotProps | `SlotPropsMap & { image?: ImgHTMLAttributes; }` |
| ButtonSize | `'small' \| 'base' \| 'large'` |
## When to use
attaching files to a form, a review-then-send batch, an avatar/image picker. Not this — use `takeoff-input` for plain text entry, and wrap in `takeoff-field` when you need a label, helper text, or error copy.
---
# Components
Browse the shipped `@takeoff-ui/react-spar` component surface. Each reference
includes live examples, public props, compound parts, stable data attributes,
and accessibility guidance where the component owns interaction behavior.
## Actions & form controls
| Component | Use it for |
| ------------------------------------- | ---------------------------------------------------------------------- |
| [Button](/docs/components/button) | Triggering actions with loading, toggle, and icon support. |
| [Checkbox](/docs/components/checkbox) | Selecting multiple options or representing a mixed state. |
| [Dropdown](/docs/components/dropdown) | Presenting contextual action menus from a trigger. |
| [Input](/docs/components/input) | Building text inputs with labels, affixes, icons, chips, and actions. |
| [Label](/docs/components/label) | Labeling controls, sections, and compact metadata. |
| [Radio](/docs/components/radio) | Choosing one option from a mutually exclusive set. |
| [Select](/docs/components/select) | Choosing from a keyboard-accessible list with typeahead. |
| [Switch](/docs/components/switch) | Turning a single setting on or off. |
| [Upload](/docs/components/upload) | Selecting and validating files with browse, drag-and-drop, and a list. |
## Navigation & disclosure
| Component | Use it for |
| ----------------------------------------- | ---------------------------------------------------------- |
| [Accordion](/docs/components/accordion) | Organizing related details into collapsible sections. |
| [Breadcrumb](/docs/components/breadcrumb) | Showing the current location within a hierarchy. |
| [Tabs](/docs/components/tabs) | Switching between related panels without leaving the task. |
## Feedback & status
| Component | Use it for |
| ------------------------------------- | ------------------------------------------------------------------------ |
| [Alert](/docs/components/alert) | Presenting contextual success, warning, information, or danger messages. |
| [Badge](/docs/components/badge) | Displaying compact status, count, or category labels. |
| [Chip](/docs/components/chip) | Representing filters, selections, and removable values. |
| [Progress](/docs/components/progress) | Showing determinate task or process completion. |
| [Skeleton](/docs/components/skeleton) | Reserving layout while content is loading. |
| [Spinner](/docs/components/spinner) | Communicating indeterminate loading work. |
| [Stepper](/docs/components/stepper) | Guiding users through a sequenced multi-step flow. |
| [Toast](/docs/components/toast) | Showing transient confirmations, alerts, and background task updates. |
| [Tooltip](/docs/components/tooltip) | Adding short contextual information on hover or focus. |
## Content & overlays
| Component | Use it for |
| ----------------------------------- | -------------------------------------------------------------- |
| [Card](/docs/components/card) | Grouping related content, summaries, and actions. |
| [Dialog](/docs/components/dialog) | Handling focused forms, confirmations, and blocking decisions. |
| [Divider](/docs/components/divider) | Separating content sections with an optional aligned label. |
| [Drawer](/docs/components/drawer) | Showing navigation, filters, or details over the current page. |
| [Popover](/docs/components/popover) | Displaying additional content or actions in a floating panel. |
| [Table](/docs/components/table) | Scanning, sorting, filtering, and paginating structured data. |
Start with [Composition & styling](/docs/foundations/composition-styling) to
learn the shared compound, slot, and customization model.
---
# React Hook Form
Build forms by letting React Hook Form manage values, validation, submission,
and field state. Use Takeoff `Field` components for the visible field anatomy:
label, description, invalid state, and error message.
## Demo
The form below shows the field structure and error display behavior.
```tsx
function BookingRequestDemo() {
const formSchema = z.object({
title: z
.string()
.min(5, 'Title must be at least 5 characters.')
.max(48, 'Title must be at most 48 characters.'),
cabin: z.string().min(1, 'Select a cabin.'),
accepted: z.boolean().refine(Boolean, 'You must accept the terms.'),
});
const form = useForm({
resolver: zodResolver(formSchema),
defaultValues: {
title: '',
cabin: '',
accepted: false,
},
});
return (
);
}
render( (
Request title
Use a short, specific title.
{fieldState.invalid ? (
{fieldState.error?.message}
) : null}
)}
/>
```
## Form
### Create a Form Schema
Define the shape and validation messages for the form. The example below uses
Zod, but the field anatomy stays the same with any resolver supported by React
Hook Form.
```tsx
import * as z from 'zod';
const formSchema = z.object({
title: z
.string()
.min(5, 'Title must be at least 5 characters.')
.max(48, 'Title must be at most 48 characters.'),
cabin: z.string().min(1, 'Select a cabin.'),
accepted: z.boolean().refine(Boolean, 'You must accept the terms.'),
});
```
### Set Up the Form
Create the form instance with `useForm`, pass the schema resolver, and define
default values for every field.
```tsx
import { zodResolver } from '@hookform/resolvers/zod';
import { useForm } from 'react-hook-form';
import * as z from 'zod';
type FormValues = z.infer;
export function BookingRequestForm() {
const form = useForm({
resolver: zodResolver(formSchema),
defaultValues: {
title: '',
cabin: '',
accepted: false,
},
});
function onSubmit(values: FormValues) {
console.log(values);
}
return (
);
}
```
### Build the Form
Use `Controller` for each field and map `fieldState` into `Field`.
```tsx
import { Controller } from 'react-hook-form';
import { Button, Checkbox, Field, Input, Select } from '@takeoff-ui/react-spar';
export function BookingRequestForm() {
const form = useForm({
resolver: zodResolver(formSchema),
defaultValues: {
title: '',
cabin: '',
accepted: false,
},
});
return (
);
}
```
### Done
When the user submits, React Hook Form validates the data and calls your submit
handler with the validated values. Invalid fields receive `fieldState.invalid`,
and each field can render its own `Field.ErrorMessage`.
## Validation
### Client-Side Validation
Schema validation lives in the `resolver` option. Field rendering does not need
to know where the error came from; it only reads `fieldState`.
```tsx
const form = useForm({
resolver: zodResolver(formSchema),
defaultValues: {
title: '',
cabin: '',
accepted: false,
},
});
```
### Validation Modes
React Hook Form supports different validation modes:
| Mode | Description |
| ----------- | ---------------------------------------------------- |
| `onSubmit` | Validate on submit. This is the default. |
| `onBlur` | Validate when a field loses focus. |
| `onChange` | Validate on every change. |
| `onTouched` | Validate after the first blur, then on every change. |
| `all` | Validate on both blur and change. |
```tsx
const form = useForm({
resolver: zodResolver(formSchema),
mode: 'onBlur',
});
```
## Displaying Errors
Display errors next to the field they belong to. For styling and accessibility:
- Pass `fieldState.invalid` to `Field invalid`.
- Pass `fieldState.invalid` to the interactive control with `aria-invalid`.
- Render `Field.ErrorMessage` only when the field is invalid.
```tsx
(
Request title
{fieldState.error?.message}
) : null}
)}
/>
```
## Working with Different Field Types
The field anatomy stays the same. Only the value mapping changes:
| Component | Mapping |
| ------------- | -------------------------------------------------------------------------------------------------------------- |
| `Input.Field` | Spread `field`, then add `aria-invalid={fieldState.invalid}`. |
| `Select` | Use `value={field.value}` and `onChange={field.onChange}` on `Select`; put `aria-invalid` on `Select.Trigger`. |
| `Checkbox` | Use `checked={field.value}` and `onChange={field.onChange}`. |
| `Switch` | Use `checked={field.value}` and `onChange={field.onChange}`. |
| `Radio` | Use `value={field.value}` and `onChange={field.onChange}` on the `Radio` root. |
```tsx
(
Cabin
Economy
Business
{fieldState.invalid ? (
{fieldState.error?.message}
) : null}
)}
/>
```
## Array Fields
Use `useFieldArray` when the form needs a repeatable set of fields such as
passengers, baggage items, or contact methods. Keep the array state in React
Hook Form, then render one `Field` per item.
The live demo below mirrors the same add, remove, reset, and submit flow as the
code sample.
```tsx
function PassengerArrayDemo() {
const formSchema = z.object({
passengers: z
.array(
z.object({
fullName: z.string().min(1, 'Passenger name is required.'),
}),
)
.min(1, 'Add at least one passenger.'),
});
const form = useForm({
resolver: zodResolver(formSchema),
defaultValues: {
passengers: [{ fullName: '' }],
},
});
const { fields, append, remove } = useFieldArray({
control: form.control,
name: 'passengers',
});
return (
);
}
render(
{field => {
const invalid =
field.state.meta.isTouched && !!field.state.meta.errors.length;
return (
Request title
field.handleChange(event.target.value)}
onBlur={field.handleBlur}
aria-invalid={invalid}
autoComplete="off"
/>
Use a short, specific title.
{invalid ? (
{String(field.state.meta.errors[0])}
) : null}
);
}}
```
## Form
### Create a Form Schema
Define the shape and validation messages in your validators. TanStack Form lets
you attach validation where the field lives, or provide a form-level schema with
a Standard Schema library such as Zod.
```tsx
import * as z from 'zod';
const formSchema = z.object({
title: z
.string()
.min(5, 'Title must be at least 5 characters.')
.max(48, 'Title must be at most 48 characters.'),
cabin: z.string().min(1, 'Select a cabin.'),
accepted: z.boolean().refine(Boolean, 'You must accept the terms.'),
});
type FormValues = z.infer;
```
### Set Up the Form
Create the form instance with `useForm`, pass the schema to `validators`, and
handle submit at the form level.
```tsx
import { useForm } from '@tanstack/react-form';
import * as z from 'zod';
export function BookingRequestForm() {
const form = useForm({
defaultValues: {
title: '',
cabin: '',
accepted: false,
},
validators: {
onChange: formSchema,
},
onSubmit: async ({ value }) => {
console.log(value);
},
});
return (
);
}
```
### Build the Form
Use `form.Field` for each field and map its state into `Field`.
```tsx
import { useForm } from '@tanstack/react-form';
import { Button, Checkbox, Field, Input, Select } from '@takeoff-ui/react-spar';
export function BookingRequestForm() {
const form = useForm({
defaultValues: {
title: '',
cabin: '',
accepted: false,
},
validators: {
onChange: formSchema,
},
onSubmit: async ({ value }) => {
console.log(value);
},
});
return (
);
}
```
### Done
When the user submits, TanStack Form validates the data and calls your submit
handler with the final values. Invalid fields receive errors through
`field.state.meta.errors`, and each field can render its own
`Field.ErrorMessage`.
## Validation
### Client-Side Validation
Validation lives in the field validators. Field rendering does not need to know
where the error came from; it only reads `field.state.meta.errors`.
```tsx
(!value ? 'Request title is required' : undefined),
}}
>
{/* field render */}
```
### Schema Validation with Zod
TanStack Form supports Standard Schema validators, so you can pass a Zod schema
directly to the form or to an individual field validator. This keeps the data
shape and validation rules in one place.
```tsx
import * as z from 'zod';
const formSchema = z.object({
title: z.string().min(5, 'Title must be at least 5 characters.'),
cabin: z.string().min(1, 'Select a cabin.'),
accepted: z.boolean().refine(Boolean, 'You must accept the terms.'),
});
const form = useForm({
defaultValues: {
title: '',
cabin: '',
accepted: false,
},
validators: {
onChange: formSchema,
},
onSubmit: async ({ value }) => {
console.log(value);
},
});
```
### Validation Modes
TanStack Form lets you choose when each validator runs:
| Mode | Description |
| ---------- | --------------------------------------- |
| `onChange` | Validate on every change. |
| `onBlur` | Validate when a field loses focus. |
| `onSubmit` | Validate when the form is submitted. |
| `onMount` | Validate when the form or field mounts. |
```tsx
(!value ? 'Email is required' : undefined),
onSubmit: ({ value }) =>
!value.includes('@') ? 'Enter a valid email' : undefined,
}}
>
{/* field render */}
```
## Displaying Errors
Display errors next to the field they belong to. For styling and accessibility:
- Compute `invalid` from the field meta.
- Pass that value to `Field invalid`.
- Pass the same value to the interactive control with `aria-invalid`.
- Render `Field.ErrorMessage` only when the field is invalid.
```tsx
const invalid = field.state.meta.isTouched && !!field.state.meta.errors.length;
const error = field.state.meta.errors[0];
return (
Request title
field.handleChange(event.target.value)}
onBlur={field.handleBlur}
aria-invalid={invalid}
/>
{invalid ? {error.message} : null}
);
```
If you use field-level string validators, render
`String(field.state.meta.errors[0])`. If you use a schema validator such as Zod,
render the structured error message.
## Working with Different Field Types
The field anatomy stays the same. Only the value mapping changes:
| Component | Mapping |
| ------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `Input.Field` | Use `value={field.state.value}` and pass `event.target.value` to `field.handleChange`. |
| `Select` | Use `value={field.state.value}` and `onChange={field.handleChange}` on `Select`; put `aria-invalid` on `Select.Trigger`. |
| `Checkbox` | Use `checked={field.state.value}` and `onChange={field.handleChange}`. |
| `Switch` | Use `checked={field.state.value}` and `onChange={field.handleChange}`. |
| `Radio` | Use `value={field.state.value}` and `onChange={field.handleChange}` on the `Radio` root. |
## Array Fields
Use `mode="array"` when the form needs a repeatable set of fields such as
passengers, baggage items, or contact methods. Keep the array state in TanStack
Form, then render one `Field` per item.
The live demo below mirrors the same add, remove, reset, and submit flow as the
code sample.
```tsx
function PassengerArrayDemo() {
const form = useForm({
defaultValues: {
passengers: [{ fullName: '' }],
},
onSubmit: async () => {},
});
return (
);
}
render(