# Slipstream UI — LLM Documentation Index The AI-first React component library. 80 components, each shipping a machine-readable COMPONENT_MANIFEST; this directory mirrors those manifests as markdown. - Library docs: https://slipstreamui.com/docs - Manifest registry: https://slipstreamui.com/registry/all.json - Single-file corpus: https://slipstreamui.com/llms-full.txt - shadcn-compatible install: `npx shadcn@latest add https://slipstreamui.com/registry/.json` ## Core components (@slipstream-ui/core) — 63 - [Accordion](https://slipstreamui.com/llm/components/accordion.md) — Collapsible content sections with ARIA accordion semantics and keyboard navigation - [Alert](https://slipstreamui.com/llm/components/alert.md) — Inline alert for status messages with semantic variants (destructive, success, warning, info) - [AppShell](https://slipstreamui.com/llm/components/app-shell.md) — Application frame with a sectioned sidebar, sticky header and scrolling main; the sidebar becomes a left Drawer on small screens. - [AuthLayout](https://slipstreamui.com/llm/components/auth-layout.md) — Centered authentication surface: brand, title/description, form card and footer, with size presets. - [Autocomplete](https://slipstreamui.com/llm/components/autocomplete.md) — Free-text type-ahead input with a portalled listbox: static or async options, grouped headings, descriptions and custom rows. - [Avatar](https://slipstreamui.com/llm/components/avatar.md) — A user profile image component with fallback support and accessible image loading - [Badge](https://slipstreamui.com/llm/components/badge.md) — A small status indicator component for displaying tags, counts, or status information - [Block](https://slipstreamui.com/llm/components/block.md) — Semantic container (div by default, swappable element) — the structural counterpart to Text (p). - [Breadcrumb](https://slipstreamui.com/llm/components/breadcrumb.md) — Navigation breadcrumb trail with links and current-page indicator - [Button](https://slipstreamui.com/llm/components/button.md) — A clickable button component with variants for different visual styles and sizes - [ButtonGroup](https://slipstreamui.com/llm/components/button-group.md) — Joins buttons into one segmented control: adjacent borders collapse, middle corners square off, and only the outer corners stay rounded — a single outline around the group. - [Card](https://slipstreamui.com/llm/components/card.md) — A content container with header, body, and footer sections for grouping related information - [Checkbox](https://slipstreamui.com/llm/components/checkbox.md) — A native checkbox input styled to match the design system, plus CheckboxGroup for grouping related options under an accessible legend - [ConfirmDialog](https://slipstreamui.com/llm/components/confirm-dialog.md) — Accessible confirmation dialog with async pending state, destructive variant and cancellable actions, built on Dialog. - [DataTable](https://slipstreamui.com/llm/components/data-table.md) — Config-driven table: one component plus a columns config that owns shape, sorting, pagination, and row interaction. - [DatePicker](https://slipstreamui.com/llm/components/date-picker.md) — Native date field with an ISO-string contract, min/max passthrough and an optional clear button. - [Dialog](https://slipstreamui.com/llm/components/dialog.md) — Accessible modal dialog with focus trap/restore, backdrop and Escape dismissal, size presets, optional header/footer slots, a scrollable body, and opt-in fade motion. - [Drawer](https://slipstreamui.com/llm/components/drawer.md) — Edge sheet for secondary flows: slides from any side (sm/md/lg), with Dialog-grade modal semantics (portal, focus trap, Escape, focus restoration). - [EmptyState](https://slipstreamui.com/llm/components/empty-state.md) — Placeholder for empty collections, zero-result searches and unconfigured features, with title, description and action slots. - [Fieldset](https://slipstreamui.com/llm/components/fieldset.md) — Groups related form controls in a native fieldset with a legend, optional description, and an error slot. - [FileUpload](https://slipstreamui.com/llm/components/file-upload.md) — Drag-and-drop file picker with a removable file list and per-file progress bars. - [FilterBar](https://slipstreamui.com/llm/components/filter-bar.md) — List-page filter strip: search field, filter controls, reset affordance and trailing actions. - [Flex / FlexItem](https://slipstreamui.com/llm/components/flex.md) — Typed flexbox container (direction/align/justify/wrap/gap) with FlexItem for per-child grow/shrink/basis controls. - [Form](https://slipstreamui.com/llm/components/form.md) — Semantic form element with even-spacing layouts: stacked (default), bordered card, or inline row — native submit and validation untouched. - [FormField](https://slipstreamui.com/llm/components/form-field.md) — Label + control + hint/error in one unit with htmlFor, aria-describedby, and aria-invalid wiring applied automatically. - [FormLayout](https://slipstreamui.com/llm/components/form-layout.md) — Groups form fields with even, tokenized spacing: vertical stack, horizontal row, or 1-4 column grid, optionally as a semantic fieldset. - [Grid / GridItem](https://slipstreamui.com/llm/components/grid.md) — Typed CSS grid with column counts per breakpoint (literal utilities that survive purging), auto-fit min-column mode, and GridItem spans. - [Heading](https://slipstreamui.com/llm/components/heading.md) — Semantic heading (h1-h6) with a safe default scale and an optional visual-size override. - [Input](https://slipstreamui.com/llm/components/input.md) — A text input field with support for various input types and standard HTML input attributes - [InputGroup](https://slipstreamui.com/llm/components/input-group.md) — Composite input shell with flush left/right addons (icons, units, buttons) behind one outer outline; the nested field sheds its own border so the group reads as a single control. - [Label](https://slipstreamui.com/llm/components/label.md) — An accessible form label that associates with its control - [Link](https://slipstreamui.com/llm/components/link.md) — Inline link primitive with default/muted/underline/arrow/external variants, asChild router support and safe external handling. - [List / ListItem](https://slipstreamui.com/llm/components/list.md) — Semantic list (ul/li) for rows of related items: settings, results, nav — with leading/trailing slots, selection, and pressable rows. - [Menu](https://slipstreamui.com/llm/components/menu.md) — Dropdown menu with keyboard navigation, typeahead, and ARIA menu semantics - [MetricCard](https://slipstreamui.com/llm/components/metric-card.md) — KPI tile: label, value, directional delta (arrow + color) and supporting hint. - [PageHeader](https://slipstreamui.com/llm/components/page-header.md) — Standard page heading: optional breadcrumbs, level-1 title, description, right-aligned actions and a sub-row slot. - [Pagination](https://slipstreamui.com/llm/components/pagination.md) — Numeric pagination with prev/next and boundary jumps; accepts page/pageCount or currentPage/totalPages and derives the count (plus a Showing X-Y of Z summary) from total/pageSize. - [PasswordInput](https://slipstreamui.com/llm/components/password-input.md) — Password field with an accessible show/hide toggle (aria-pressed), built on Input. - [Popover](https://slipstreamui.com/llm/components/popover.md) — Floating panel anchored to a trigger with interactive content, closing on outside click and Escape - [Progress](https://slipstreamui.com/llm/components/progress.md) — A determinate progress bar with role=progressbar and exact value semantics - [Prose](https://slipstreamui.com/llm/components/prose.md) — Self-contained long-form typography for rendered markdown/MDX: headings, links, lists, code, tables, quotes and figures. - [Radio](https://slipstreamui.com/llm/components/radio.md) — Native radio buttons grouped for mutually exclusive choices, with an accessible fieldset/legend wrapper - [Search](https://slipstreamui.com/llm/components/search.md) — Select-with-search: type to filter a full-width dropdown of options, or arrow through the full set from an empty query. - [SectionHeading](https://slipstreamui.com/llm/components/section-heading.md) — Section heading block: eyebrow, title (level 2-4), description and actions, with left/center alignment and three sizes. - [Select](https://slipstreamui.com/llm/components/select.md) — Accessible select built on the native ``` ## Anti-patterns - **Don't put the primary action in the bar** — FilterBar is for narrowing; creation actions belong in PageHeader actions. ## Accessibility - **Search landmark**: Wraps controls in role=search; the search input is labelled by its placeholder ## Composition - Compose with **Select** — Filter controls render in children ```tsx setName(e.target.value)} /> setEmail(e.target.value)} /> ``` ### Card and inline variants ```tsx ``` ## Anti-patterns - **Don't nest forms** — Nested ``` - Compose with **FormLayout** — Multi-column or grouped sections inside a form - Compose with **Button** — Submit button with type="submit" — native Enter handling comes free - Related: FormField, FormLayout, Fieldset, Input --- # FormField Label + control + hint/error in one unit with htmlFor, aria-describedby, and aria-invalid wiring applied automatically. > Import: `import { FormField } from '@slipstream-ui/core'` > Registry: https://slipstreamui.com/registry/form-field.json > Tier: molecule · Package: @slipstream-ui/core ## Design intent Every form control needs the same trio — label, hint or error, correct ARIA wiring — and hand-wiring it is where accessibility regressions start. FormField clones id/aria-describedby/aria-invalid onto a single-element child so the common case is one component and zero boilerplate. ## Props | Prop | Type | Default | Required | Description | |---|---|---|---|---| | id | `string` | — | yes | The control's id — shared with the label's htmlFor and the hint/error ids. | | label | `string` | — | yes | Visible label text (kept for screen readers even when labelHidden). | | hint | `string` | — | no | Helper text under the control, wired via aria-describedby. | | error | `string` | — | no | Validation error; replaces the hint, sets aria-invalid on the control, announced via role=alert. | | required | `boolean` | `false` | no | Renders the required marker next to the label. | | labelHidden | `boolean` | `false` | no | Keeps the label screen-reader visible but hides it visually (sr-only). | | trailing | `ReactNode` | — | no | Slot pinned to the far right of the label row (badge, link, action). | | tooltip | `string` | — | no | Info icon rendered after the label; opens a tooltip with this text. | | labelPlacement | `'top' | 'left'` | `top` | no | Stack the label above the control (default) or inline it to the left. | ## Examples ### Text input with hint The cloned child receives id, aria-describedby, and the label pairs via htmlFor. ```tsx ``` ### Error state Error replaces the hint, flips aria-invalid on the control, and announces via role=alert. ```tsx setEmail(e.target.value)} /> ``` ### Search-style field ```tsx ``` ## Anti-patterns - **Don't rely on placeholder as the label** — Placeholders disappear on input and fail color-contrast rules. FormField renders a real ; use placeholder only for example format. - **Don't nest multiple controls in one FormField** — The aria wiring (describedby/invalid) clones onto exactly one child element. For groups, use Fieldset or one FormField per control. - **Don't duplicate ids across fields** — id keys the whole wiring — every FormField in a form must receive a unique id and the child must not override it with a different value. ## Accessibility - **Label association**: Renders and clones the same id onto single-element children - **Hint and error wiring**: aria-describedby points at the hint (or the error when present); errors render with role=alert - **Invalid state**: Sets aria-invalid on the cloned control when error is present - **Required marker**: The asterisk is aria-hidden; native required semantics come from the control's own required attribute ## Composition - Compose with **Input / Textarea / Select / Search / Autocomplete** — Wrap exactly one control — id/aria wiring is cloned onto it automatically ```tsx ``` - Compose with **Fieldset** — Use Fieldset (not FormField) when the label names a GROUP of controls - Related: Label, Input, Fieldset, Search, Autocomplete --- # FormLayout Groups form fields with even, tokenized spacing: vertical stack, horizontal row, or 1-4 column grid, optionally as a semantic fieldset. > Import: `import { FormLayout } from '@slipstream-ui/core'` > Registry: https://slipstreamui.com/registry/form-layout.json > Tier: molecule · Package: @slipstream-ui/core ## Design intent Field rhythm is the difference between a form that scans and one that doesn't. FormLayout owns the ARRANGEMENT (stack/row/grid + exact gap) while Fieldset owns the group semantics (legend) and FormField owns per-control wiring — three small pieces instead of one magic wrapper. ## Props | Prop | Type | Default | Required | Description | |---|---|---|---|---| | layout | `'stack' | 'row' | 'grid'` | `stack` | no | Grouping layout: even vertical stack, horizontal row, or column grid. | | columns | `1 | 2 | 3 | 4` | `2` | no | Grid column count (literal classes survive CSS purging). | | gap | `'none' | 'sm' | 'md' | 'lg' | 'xl' | number` | — | no | Even spacing between children — token or exact pixels (16). | | legend | `string` | — | no | Group label rendered as a semantic (fieldset mode). | | description | `string` | — | no | Supporting line under the legend (fieldset mode). | | as | `'div' | 'fieldset'` | `div` | no | Render as a semantic fieldset when the layout names a group of controls. | ## Examples ### Two-column settings grid Exact 16px gaps; fields wrap into rows of two. ```tsx ``` ### Inline action row ```tsx ``` ## Anti-patterns - **Don't hand-roll spacer divs** — Empty divs with heights drift from the token scale and break under different densities — gap exists for spacing. - **Don't use fieldset mode without a legend** — as="fieldset" without legend renders an unnamed group — assistive tech announces nothing useful. Prefer div, or provide the legend. ## Accessibility - **Fieldset mode gives the group a name**: legend renders as a real ; use it whenever the layout wraps related controls - **Reading order equals DOM order**: Row/grid layouts reflow visually; source order never changes ## Composition - Compose with **FormField** — FormLayout arranges the fields; each field keeps its own FormField wiring ```tsx … ``` - Compose with **Form** — Layouts live inside a Form (or standalone for filter bars) - Compose with **Fieldset** — Fieldset when the legend/grouping IS the point; FormLayout when spacing/arrangement is - Related: FormField, Form, Fieldset, Grid --- # Grid / GridItem Typed CSS grid with column counts per breakpoint (literal utilities that survive purging), auto-fit min-column mode, and GridItem spans. > Import: `import { Grid } from '@slipstream-ui/core'` > Registry: https://slipstreamui.com/registry/grid.json > Tier: molecule · Package: @slipstream-ui/core ## Design intent Grid layout should be declarative without stepping on Tailwind's compiler: column counts map to literal class names the scanner can see, and responsive card grids use minmax() auto-fit via minCol — no breakpoint math, no purged runtime-built classes. GridItem adds per-cell spans with the same literal approach. ## Props | Prop | Type | Default | Required | Description | |---|---|---|---|---| | cols | `number` | `auto (minCol) or browser default` | no | Base column count (1-6). | | smCols | `number` | — | no | Columns from the sm breakpoint up (1-6). | | mdCols | `number` | — | no | Columns from the md breakpoint up (1-6). | | lgCols | `number` | — | no | Columns from the lg breakpoint up (1-6). | | minCol | `string` | `undefined` | no | Auto-fit mode: repeat(auto-fit, minmax(, 1fr)) — cards wrap responsively. Overrides the cols* props. | | gap | `'none' | 'sm' | 'md' | 'lg' | 'xl'` | `md` | no | Token gap between cells. | | as | `'div' | 'span' | 'section' | 'ul'` | — | no | Semantic element (use 'ul' with GridItem as="li" for item grids). | | span | `number` | — | no | GridItem column span at the base breakpoint (1-6). | | smSpan | `number` | — | no | GridItem column span from sm up (1-6). | | mdSpan | `number` | — | no | GridItem column span from md up (1-6). | | lgSpan | `number` | — | no | GridItem column span from lg up (1-6). | ## Examples ### Responsive card grid (auto-fit) minmax() wrapping — works at every width without breakpoint columns. ```tsx {cards.map((c) => ( … ))} ``` ### Fixed columns with a hero span Literal grid-cols-*/col-span-* classes are compiled (they exist verbatim in source). ```tsx Hero Card A Card B ``` ## Anti-patterns - **Don't build column classes at runtime** — Template-built utilities (md:grid-cols-${n}) are invisible to Tailwind's scanner and get purged — the grid silently collapses to one column. The cols props use pre-declared literal classes. - **Don't nest grids for one-axis layouts** — Row/column alignment is Flex's job; nesting grids adds template complexity with no benefit. ## Accessibility - **Layout-only semantics**: Renders div/section/ul — no interactive behavior added - **Reading order equals DOM order**: Visual column reflow never reorders DOM nodes ## Composition - Compose with **Flex** — Flex for one-axis rows; Grid for two-axis layout - Compose with **Card** — The classic minCol grid cell — cards wrap responsively - Related: Flex, Card, Block --- # Heading Semantic heading (h1-h6) with a safe default scale and an optional visual-size override. > Import: `import { Heading } from '@slipstream-ui/core'` > Registry: https://slipstreamui.com/registry/heading.json > Tier: atom · Package: @slipstream-ui/core ## Design intent Document structure and visual size are different axes: screen readers and SEO need the correct h-level, while design sometimes needs a smaller visual size. Heading takes level (semantic) and size (visual) separately so outline integrity never gets sacrificed for typography. ## Props | Prop | Type | Default | Required | Description | |---|---|---|---|---| | level | `1 | 2 | 3 | 4 | 5 | 6` | — | yes | Semantic level — renders the matching h1..h6 element. | | size | `'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl'` | — | no | Visual size override, independent of the semantic level. | | muted | `boolean` | `false` | no | Use the muted-foreground token instead of the primary text color. | ## Examples ### Structural heading with visual override ```tsx Section title {/* h4 semantics (correct outline position) but large visual size) */} Card headline ``` ### Muted subheading ```tsx Supporting label ``` ## Anti-patterns - **Never skip levels for styling** — Jumping h1 -> h3 breaks the outline assistive tech announces. Use size for visual weight; level stays sequential. - **Don't use Text as a heading** — A bolded paragraph is not a heading: navigation panes and find-in-page won't index it. ## Accessibility - **Correct heading elements**: Renders h1..h6 from the level prop; default scale keeps visual hierarchy aligned with structure - **Tokenized color**: muted uses --muted-foreground (AA in both themes) ## Composition - Compose with **Text** — Headings introduce sections; Text carries the prose - Related: Text, Block --- # InlineCitation Perplexity-style inline citation chip that reveals the source title and snippet on hover or keyboard focus. > Import: `import { InlineCitation } from '@slipstream-ui/ai'` > Registry: https://slipstreamui.com/registry/inline-citation.json > Tier: atom · Package: @slipstream-ui/ai ## Design intent Attribute individual claims inside a response to their source without leaving the paragraph. ## Props | Prop | Type | Default | Required | Description | |---|---|---|---|---| | source | `SourceItem` | — | yes | Cited source powering the preview card. | | children | `ReactNode` | — | no | Wrapped text; defaults to the source title. | ## Examples ### Wrap a claim ```tsx as reported ``` ## Anti-patterns - **Do not stack many citations on one word** — Use Sources footer for long lists; keep inline citations to one claim each. ## Accessibility - **Keyboard access**: Trigger is a focusable button; card opens on focus-within. - **Tooltip semantics**: Card has role=tooltip linked via aria-describedby. --- # Input A text input field with support for various input types and standard HTML input attributes > Import: `import { Input } from '@slipstream-ui/core'` > Registry: https://slipstreamui.com/registry/input.json > Tier: atom · Package: @slipstream-ui/core ## Design intent The Input component provides a styled text input that follows the design system. It supports all standard HTML input attributes and includes proper focus states, disabled states, and file input styling. ## Props | Prop | Type | Default | Required | Description | |---|---|---|---|---| | type | `string` | `text` | no | HTML input type (text, password, email, number, etc.) | | placeholder | `string` | — | no | Placeholder text to display when input is empty | | value | `string` | — | no | Current value of the input (controlled component) | | defaultValue | `string` | — | no | Default value for uncontrolled input | | disabled | `boolean` | `false` | no | Disables the input | | required | `boolean` | `false` | no | Marks the input as required for form validation | | onChange | `(event: ChangeEvent) => void` | — | no | Handler called when input value changes | | onFocus | `(event: FocusEvent) => void` | — | no | Handler called when input is focused | | onBlur | `(event: FocusEvent) => void` | — | no | Handler called when input loses focus | ## Examples ### Basic text input Simple text input with placeholder ```tsx ``` ### Email input Input optimized for email addresses ```tsx ``` ### Password input Input that obscures text for passwords ```tsx ``` ### Controlled input Input with controlled state ```tsx setValue(e.target.value)} placeholder="Controlled input" /> ``` ### Disabled input Input that cannot be interacted with ```tsx ``` ### File input Input for file uploads with styled file button ```tsx ``` ## Anti-patterns - **Don't use Input for multi-line text** — Input is for single-line text. Use Textarea for multi-line content. - **Don't ignore validation** — Provide visual feedback for validation errors - **Don't use vague placeholders** — Placeholders should describe what input is expected ## Accessibility - **Keyboard navigation**: Input is natively focusable and supports all keyboard input - **Screen reader support**: Input type and placeholder are announced. Use aria-label or aria-labelledby for additional context - **Form validation**: Supports HTML5 validation attributes (required, pattern, min, max) - **Disabled state**: Disabled inputs are not focusable and screen readers announce as disabled ## Composition - Compose with **Label** — Inputs should always have associated labels for accessibility ```tsx Email ``` - Compose with **Form** — Inputs are typically used within form components for validation and submission ```tsx Form groups multiple inputs together for validation ``` - Related: Textarea, Label, Form, Select --- # InputGroup Composite input shell with flush left/right addons (icons, units, buttons) behind one outer outline; the nested field sheds its own border so the group reads as a single control. > Import: `import { InputGroup } from '@slipstream-ui/core'` > Registry: https://slipstreamui.com/registry/input-group.json > Tier: molecule · Package: @slipstream-ui/core ## Design intent Search fields, URL/unit inputs, and inline actions need affixes that sit flush inside the field. InputGroup owns the combined border and focus ring (the outline doubles as the affordance) while addons stay visually part of the field: ghost addons keep the group background, muted addons paint a light gray, and nested inputs are stripped of their own chrome via descendant selectors. ## Props | Prop | Type | Default | Required | Description | |---|---|---|---|---| | side | `'left' | 'right'` | `left` | no | Edge the addon hugs (flush against the group outline). | | variant | `'ghost' | 'muted'` | `ghost` | no | Addon surface: ghost keeps the group background, muted paints a light gray. | ## Examples ### URL field with unit affixes Muted affixes carry the fixed parts of the value; only the middle is editable. ```tsx https:// .com ``` ### Search with icon and action button Leading icon is decorative; the trailing button is the pseudo action indicator. ```tsx ``` ### Numeric input with currency suffix The unit sits flush right; the outline communicates editability. ```tsx PLN ``` ## Anti-patterns - **Don't give nested inputs their own border** — The group's outer border is the control outline. Inner borders create double lines and break the flush-addon look — strip them with the group (built in) or avoid nesting a bordered Input. - **Don't nest interactive elements without labels** — Addon buttons live inside the field's focus-within region; they still need accessible names and must not steal the field's label association. ## Accessibility - **Single focus stop**: Focus ring renders on the group via focus-within; nested inputs keep keyboard focus and their label association (htmlFor/id still targets the input) - **Decorative affixes**: Purely decorative icons/text in addons should carry aria-hidden or the input's aria-label should include the unit - **Disabled state**: Nested input's disabled styling applies; addons are independent — disable buttons inside them yourself ## Composition - Compose with **Input / Textarea / Select** — The nested field is the editable region; InputGroup strips its border/ring automatically ```tsx @ ``` - Compose with **FormField** — Wrap the whole group when it needs a persistent label or error ```tsx … ``` - Compose with **Button** — Buttons inside addons are the action affordance — ghost/variant='ghost' keeps the flush look ```tsx ``` - Related: Input, FormField, Search, Button --- # Label An accessible form label that associates with its control > Import: `import { Label } from '@slipstream-ui/core'` > Registry: https://slipstreamui.com/registry/label.json > Tier: atom · Package: @slipstream-ui/core ## Design intent Label names a form control so screen readers announce the field name together with its value and state. Use htmlFor to associate, or wrap the control. ## Props | Prop | Type | Default | Required | Description | |---|---|---|---|---| | htmlFor | `string` | — | no | The id of the control this label describes | | children | `ReactNode` | — | yes | The label text | | className | `string` | — | no | Additional CSS classes to apply | ## Examples ### Label with input Associated label and input ```tsx Email ``` ### Required field Marking required fields explicitly ```tsx Name (required) ``` ## Anti-patterns - **Don't use placeholder as a label** — Placeholders disappear on input and are skipped by many screen readers. ## Accessibility - **Programmatic association**: htmlFor/id pairing links the label to its control ## Composition - Compose with **Input** — Every input should have a label ```tsx Email ``` - Related: Input, Textarea, Select, Checkbox, Radio --- # Link Inline link primitive with default/muted/underline/arrow/external variants, asChild router support and safe external handling. > Import: `import { Link } from '@slipstream-ui/core'` > Registry: https://slipstreamui.com/registry/link.json > Tier: atom · Package: @slipstream-ui/core ## Design intent Every codebase re-implements inline links with inconsistent variants and unsafe target=_blank. Link centralizes the variants, keeps a real (SEO, modified clicks) and adds rel=noopener plus a screen-reader note for external URLs. ## Props | Prop | Type | Default | Required | Description | |---|---|---|---|---| | href | `string` | — | no | Destination URL (pass through or via asChild). | | variant | `'default' | 'muted' | 'underline' | 'arrow' | 'external'` | `default` | no | Visual style. | | asChild | `boolean` | `false` | no | Render the child (router Link) with link styling. | | external | `boolean` | — | no | Force external handling; absolute http(s) URLs are auto-detected, mailto/tel never open a new tab. | ## Examples ### Inline link Internal links stay client-side; absolute URLs open safely in a new tab. ```tsx Read the docs GitHub ``` ### Router link Preserves prefetch and modified-click behavior. ```tsx Posts ``` ## Anti-patterns - **Don't use Link for buttons** — Actions belong in Button; Link is for navigation. ## Accessibility - **Real anchors**: Renders so middle-click/modified clicks work - **External notice**: External links get rel=noopener noreferrer and a screen-reader note ## Composition - Compose with **Card / List** — asChild makes whole-card links safe ```tsx … ``` - Related: Button, Breadcrumb, Card --- # List / ListItem Semantic list (ul/li) for rows of related items: settings, results, nav — with leading/trailing slots, selection, and pressable rows. > Import: `import { List } from '@slipstream-ui/core'` > Registry: https://slipstreamui.com/registry/list.json > Tier: molecule · Package: @slipstream-ui/core ## Design intent Row collections are lists, not tables or div stacks: screen readers announce item counts and navigate by item. List/ListItem keep that semantics while providing the layout vocabulary (slots, dividers, density, selection) that real product UIs need — and a pressable row wraps its content in a button so ul > li structure stays valid. ## Props | Prop | Type | Default | Required | Description | |---|---|---|---|---| | divided | `boolean` | `false` | no | Hairline dividers between rows (List). | | bordered | `boolean` | `false` | no | Card-like surface and border around the list (List). | | size | `'default' | 'compact'` | `default` | no | Row density (List). | | leading | `ReactNode` | — | no | Leading slot: icon, avatar, status dot, or checkbox (ListItem). | | trailing | `ReactNode` | — | no | Trailing slot: chevron, badge, meta, or action (ListItem). | | selected | `boolean` | `false` | no | Marks the row as the active/selected item (ListItem). | | description | `string` | — | no | Secondary line under the main content (ListItem). | | onClick | `() => void` | — | no | Makes the row pressable — content renders inside a full-width button so list semantics stay intact (ListItem). | ## Examples ### Settings rows with selection selected highlights the active row; description adds a sub-line. ```tsx } trailing={new} selected> Notifications } description="Weekly digest every Monday"> Digest ``` ### Pressable rows onClick renders the row content inside a } /> ``` ## Anti-patterns - **Don't stack multiple h1s** — PageHeader renders the page's h1; section headings inside the page should be h2 via Heading. ## Accessibility - **Heading hierarchy**: Renders exactly one level-1 heading ## Composition - Compose with **Breadcrumb** — Pass a Breadcrumb as breadcrumbs for hierarchy context ```tsx } title="Detail" /> ``` - Related: Breadcrumb, Heading, Tabs --- # Pagination Numeric pagination with prev/next and boundary jumps; accepts page/pageCount or currentPage/totalPages and derives the count (plus a Showing X-Y of Z summary) from total/pageSize. > Import: `import { Pagination } from '@slipstream-ui/core'` > Registry: https://slipstreamui.com/registry/pagination.json > Tier: molecule · Package: @slipstream-ui/core ## Design intent Pagination lets users navigate through paged content. It shows page numbers with ellipsis for large ranges, prev/next buttons, and marks the current page with aria-current=page. ## Props | Prop | Type | Default | Required | Description | |---|---|---|---|---| | page | `number` | `1` | no | Current page (1-based). Alias: currentPage. | | pageCount | `number` | — | no | Total pages. Alias: totalPages, or derived from total/pageSize. | | currentPage | `number` | — | no | Alias for page (migration-friendly). | | totalPages | `number` | — | no | Alias for pageCount. | | pageSize | `number` | — | no | Rows per page; with total enables the summary and derives pageCount. | | total | `number` | — | no | Total item count for the summary. | | itemLabel | `string` | `items` | no | Noun used in the summary. | | showSummary | `boolean` | — | no | Force the summary on/off (defaults on when total and pageSize are set). | | onPageChange | `(page: number) => void` | — | no | Called with the new page number. | | siblings | `number` | `1` | no | Page buttons shown around the current page. | | showBoundaries | `boolean` | `false` | no | Show first/last jump buttons. | | showFirst | `boolean` | — | no | Force-show the first-page button. | | showLast | `boolean` | — | no | Force-show the last-page button. | | icons | `PaginationIcons` | — | no | Replace the default glyphs. | | labels | `{ pagination?: string; first?: string; previous?: string; next?: string; last?: string; page?: (page: number) => string }` | — | no | Localized landmark and control labels. | ## Examples ### Summary + derived pages Renders "Showing 26–50 of 312 students" and derives 13 pages. ```tsx ``` ### Migration aliases currentPage/totalPages map onto page/pageCount. ```tsx ``` ### Basic pagination Navigate through 10 pages ```tsx ``` ### Wide page range Show more page buttons around the current page ```tsx ``` ## Anti-patterns - **Don't use Pagination for infinite scroll content** — Pagination implies discrete pages. Use a 'Load more' button or infinite scroll for continuous content. - **Don't hide the current page number** — Users need to know where they are. Always show the active page with aria-current=page. ## Accessibility - **Navigation landmark**: nav[aria-label=Pagination] - **Current page**: Active button has aria-current=page - **Disabled buttons**: Prev/next are disabled at the boundaries ## Composition - Compose with **Table** — Paginate long table data ```tsx ...

``` - Related: Table, Breadcrumb --- # PasswordInput Password field with an accessible show/hide toggle (aria-pressed), built on Input. > Import: `import { PasswordInput } from '@slipstream-ui/core'` > Registry: https://slipstreamui.com/registry/password-input.json > Tier: molecule · Package: @slipstream-ui/core ## Design intent Users mistype passwords; a reveal toggle reduces failed sign-ins. The toggle must be a real button with a pressed state and a proper label so it is not a mystery control. ## Props | Prop | Type | Default | Required | Description | |---|---|---|---|---| | showLabel | `string` | `Show password` | no | Accessible label while hidden. | | hideLabel | `string` | `Hide password` | no | Accessible label while visible. | ## Examples ### Sign-in field Input props pass through. ```tsx ``` ## Anti-patterns - **Don't reveal by default** — Start masked; reveal is user-initiated. ## Accessibility - **Toggle semantics**: Button with aria-pressed and Show/Hide labels ## Composition - Compose with **FormField** — Wrap for label/hint/error wiring ```tsx ``` - Related: Input, FormField, InputGroup --- # Popover Floating panel anchored to a trigger with interactive content, closing on outside click and Escape > Import: `import { Popover } from '@slipstream-ui/core'` > Registry: https://slipstreamui.com/registry/popover.json > Tier: molecule · Package: @slipstream-ui/core ## Design intent Popover displays interactive content (links, buttons, forms) in a floating panel. Unlike Tooltip, the content is focusable and actionable. Closes on outside click and Escape. ## Props | Prop | Type | Default | Required | Description | |---|---|---|---|---| | open | `boolean` | — | no | Controlled open state | | onOpenChange | `(open: boolean) => void` | — | no | Called when the open state changes | | children | `ReactNode` | — | yes | PopoverTrigger and PopoverContent children | | className | `string` | — | no | Additional CSS classes to apply | ## Examples ### Simple popover Popover with text and a button ```tsx Details

More information here.

``` ### Controlled popover Popover driven by parent state ```tsx Options ``` ## Anti-patterns - **Don't use Popover for plain text hints** — Use Tooltip for non-interactive hints. Popover is for interactive content. - **Don't use Popover for critical forms or destructive actions** — Popovers close on outside click, which can interrupt form filling. Use Dialog for forms and destructive confirmations. ## Accessibility - **Dialog semantics**: role=dialog with aria-labelledby linking to the trigger - **Escape dismissal**: Escape closes the popover ## Composition - Compose with **PopoverTrigger** — Every Popover needs a PopoverTrigger ```tsx Open ``` - Related: Tooltip, Dialog, Menu --- # Progress A determinate progress bar with role=progressbar and exact value semantics > Import: `import { Progress } from '@slipstream-ui/core'` > Registry: https://slipstreamui.com/registry/progress.json > Tier: atom · Package: @slipstream-ui/core ## Design intent Progress shows completion of a known-length task (uploads, installs, multi-step flows). It exposes exact values so assistive tech reports percentages, not just a moving bar. ## Props | Prop | Type | Default | Required | Description | |---|---|---|---|---| | value | `number` | `0` | no | Current value between 0 and max | | max | `number` | `100` | no | Upper bound of the progress scale | | label | `string` | — | no | Accessible label announced by screen readers | | className | `string` | — | no | Additional CSS classes to apply | ## Examples ### Upload progress Track an upload percentage ```tsx ``` ### Step completion Progress through a finite set of steps ```tsx ``` ## Anti-patterns - **Don't use Progress for indeterminate work** — When the duration is unknown, use Spinner or StreamingIndicator instead. - **Don't animate progress beyond its value** — Fabricating movement misleads users; only reflect real task progress. ## Accessibility - **Progressbar semantics**: role="progressbar" with aria-valuenow/min/max - **Exact values**: aria-valuenow reflects the clamped value ## Composition - Compose with **Skeleton** — Use Skeleton for unknown-length content, Progress for known-length tasks ```tsx ``` - Related: Skeleton, Spinner --- # PromptInput A textarea input for entering chat prompts with auto-resize, keyboard shortcuts, and send button > Import: `import { PromptInput } from '@slipstream-ui/ai'` > Registry: https://slipstreamui.com/registry/prompt-input.json > Tier: molecule · Package: @slipstream-ui/ai ## Design intent The PromptInput component provides a specialized input for chat interfaces. It handles auto-resizing as the user types, supports Enter to submit (Shift+Enter for new line), and integrates with the conversation flow. It's designed to be the primary way users interact with AI assistants. ## Props | Prop | Type | Default | Required | Description | |---|---|---|---|---| | onSubmit | `(value: string) => void` | — | yes | Callback when the user submits the prompt | | placeholder | `string` | `Type your message...` | no | Placeholder text to display when input is empty | | disabled | `boolean` | `false` | no | Whether the input is disabled | | isLoading | `boolean` | `false` | no | Whether a submission is currently in progress | | autoFocus | `boolean` | `false` | no | Whether to auto-focus the input on mount | | maxLength | `number` | — | no | Maximum character count for the input | | showSendButton | `boolean` | `true` | no | Whether to show the send button | | sendButtonText | `string` | `Send` | no | Text or icon for the send button | | className | `string` | — | no | Additional CSS classes to apply to the container | | onStop | `() => void` | — | no | While loading, the send button becomes a stop button that calls this handler. | | stopButtonText | `string` | `Stop generating` | no | Accessible label for the stop button; enables localization. | | attachments | `AttachmentItem[]` | — | no | Controlled attachment list shown as chips above the input | | onRemoveAttachment | `(id: string) => void` | — | no | Called when the user removes an attachment chip | | onAttachmentsChange | `(attachments: AttachmentItem[]) => void` | — | no | Called when files are added via drag-and-drop, paste, or picker | | hasError | `boolean` | — | no | Styles the input in an error state (e.g. after a rejected file) | | accept | `string` | — | no | MIME types accepted for attachments (e.g. "image/*") | | multiple | `boolean` | — | no | Allow selecting multiple files | | maxFiles | `number` | — | no | Maximum number of attachments allowed | | maxFileSize | `number` | — | no | Maximum file size in bytes; rejects larger files | | onAttachmentError | `(error: string) => void` | — | no | Called when an attachment is rejected (size, type, or count limit) | | globalDrop | `boolean` | — | no | Enable drop-anywhere-on-page file acceptance | | children | `ReactNode` | — | no | Custom content rendered inside the input row (e.g. tool buttons) | | tooltip | `string | { content: ReactNode; shortcut?: string }` | — | no | Tooltip content for a toolbar button; optionally includes a keyboard shortcut hint (PromptInput.Button sub-component) | | active | `boolean` | `false` | no | Toggles the active state on a toolbar button (PromptInput.Button sub-component) | ## Examples ### Basic prompt input Simple prompt input with default configuration ```tsx console.log(value)} /> ``` ### With custom placeholder Prompt input with custom placeholder text ```tsx ``` ### With auto-focus Auto-focuses the input when component mounts ```tsx ``` ### With character limit Limits input to 500 characters ```tsx ``` ### Without send button Hides the send button (user must press Enter) ```tsx ``` ### With loading state Shows loading state and disables while AI is responding ```tsx ``` ### Cancellable generation ```tsx abortRef.current.abort()} /> ``` ## Anti-patterns - **Don't use for non-chat input** — PromptInput is specifically for chat interactions, not general form input - **Don't ignore Enter key behavior** — Users expect Enter to submit. If you change this, communicate it clearly - **Don't validate after submission** — Disable the input when empty rather than validating in the handler ## Accessibility - **Keyboard navigation**: Full keyboard support with Enter to submit, Shift+Enter for new line - **Screen reader support**: Textarea has proper label and placeholder. Button state is announced - **Form validation**: Button is disabled when input is empty, preventing invalid submissions - **Auto-resize**: Textarea automatically grows with content up to max-height ## Composition - Compose with **Conversation** — PromptInput is typically used below a Conversation component to add new messages ```tsx Conversation displays messages, PromptInput submits new ones to the same messages array ``` - Compose with **ChatLayout** — PromptInput is often part of a ChatLayout that combines Conversation and input ```tsx ChatLayout wraps Conversation and PromptInput in a complete chat interface ``` - Related: Conversation, ChatLayout, Button --- # Prose Self-contained long-form typography for rendered markdown/MDX: headings, links, lists, code, tables, quotes and figures. > Import: `import { Prose } from '@slipstream-ui/core'` > Registry: https://slipstreamui.com/registry/prose.json > Tier: molecule · Package: @slipstream-ui/core ## Design intent Content sites need consistent article typography without depending on the Tailwind typography plugin. Prose styles rendered HTML via child selectors, so any remark/MDX pipeline can drop output inside. ## Props | Prop | Type | Default | Required | Description | |---|---|---|---|---| | size | `'sm' | 'md' | 'lg'` | `md` | no | Type scale for body and headings. | ## Examples ### Article body Wrap MDX/remark output; keep Shiki/KaTeX as-is. ```tsx {renderedMarkdown} ``` ## Anti-patterns - **Don't use prose for app UI** — Prose targets article content; forms and dashboards use Text/Heading. ## Accessibility - **Heading anchors**: scroll-mt offsets headings under sticky headers ## Composition - Compose with **TableOfContents** — Pair long articles with a TOC + useScrollSpy ```tsx {content} ``` - Related: TableOfContents, Heading, Text, CodeBlock --- # Radio Native radio buttons grouped for mutually exclusive choices, with an accessible fieldset/legend wrapper > Import: `import { Radio } from '@slipstream-ui/core'` > Registry: https://slipstreamui.com/registry/radio.json > Tier: atom · Package: @slipstream-ui/core ## Design intent Radio lets users pick exactly one option from a visible set. RadioGroup provides the shared name and accessible legend so screen readers announce group context. ## Props | Prop | Type | Default | Required | Description | |---|---|---|---|---| | value | `string` | — | yes | The value this item contributes to the group | | label | `string` | — | no | Visible label rendered next to the radio | | checked | `boolean` | — | no | Controlled checked state (on Radio) | | onCheckedChange | `(checked: boolean) => void` | — | no | Fired when the user selects this radio (on Radio) | | disabled | `boolean` | `false` | no | Disables the radio | | title | `string` | — | no | Section heading (RadioCard component) | | description | `string` | — | no | Supporting line under the title (RadioCard component) | | rounded | `boolean` | `true` | no | Outer border radius on the section; false gives square corners (RadioCard component) | | legend | `string` | — | no | Accessible group label; rendered as inside a fieldset (RadioGroup component) | | onValueChange | `(value: string) => void` | — | no | Called with the newly selected value (RadioGroup component) | | orientation | `'vertical' | 'horizontal'` | `vertical` | no | Stack options (default) or lay them out in a wrapping row (RadioGroup component) | | error | `string` | — | no | Group-level validation message; announced via role=alert (RadioGroup component) | | defaultValue | `string` | — | no | Initial selected value when uncontrolled (RadioGroup component) | ## Examples ### Radio group Mutually exclusive plan selection ```tsx ``` ### Controlled group Group driven by parent state ```tsx ``` ## Anti-patterns - **Don't use Radio for multi-select** — Radio is single-choice. Use Checkbox when users can pick more than one option. - **Don't render bare radios without a group** — Without RadioGroup there is no shared name or legend, so screen readers can't convey the grouping. ## Accessibility - **Group semantics**: RadioGroup renders a fieldset with a legend so the group name is announced - **Arrow-key navigation**: Native radio behavior: arrows move selection within the group ## Composition - Compose with **RadioGroup** — Always wrap Radio/RadioGroupItem in a RadioGroup ```tsx ``` - Related: Checkbox, Select, Label --- # Reasoning A collapsible component for displaying AI reasoning steps and chain-of-thought processes > Import: `import { Reasoning } from '@slipstream-ui/ai'` > Registry: https://slipstreamui.com/registry/reasoning.json > Tier: molecule · Package: @slipstream-ui/ai ## Design intent The Reasoning component displays the step-by-step thought process of an AI agent. It's collapsible to avoid cluttering the interface while still providing transparency into how the AI arrived at its conclusions. ## Props | Prop | Type | Default | Required | Description | |---|---|---|---|---| | steps | `ReasoningStep[]` | — | yes | Array of reasoning steps to display | | collapsible | `boolean` | `true` | no | Whether the reasoning can be collapsed/expanded | | defaultExpanded | `boolean` | `false` | no | Whether the reasoning is expanded by default | | className | `string` | — | no | Additional CSS classes to apply | | duration | `number` | — | no | Elapsed reasoning time in seconds; renders a duration chip | | isStreaming | `boolean` | — | no | Shows a streaming indicator while reasoning is in progress | | labels | `{ title?: string; count?: (count: number) => string; thinking?: string; step?: (index: number) => string }` | — | no | Localized header, count and step labels. | ## Examples ### Basic reasoning Collapsible reasoning with multiple steps ```tsx ``` ### Expanded by default Reasoning that shows steps immediately ```tsx ``` ### Non-collapsible Reasoning that cannot be collapsed ```tsx ``` ### With timestamps Reasoning steps with timing information ```tsx ``` ## Anti-patterns - **Don't show reasoning for simple responses** — Reasoning is valuable for complex tasks but adds noise for simple responses. - **Don't make steps too verbose** — Reasoning steps should be concise and focused on key decision points. - **Don't show empty reasoning** — The component returns null for empty arrays, but it's better to not render it at all. ## Accessibility - **Collapsible state**: Uses aria-expanded to communicate collapsible state to screen readers - **Keyboard navigation**: Collapsible button is keyboard accessible with Enter/Space to toggle - **Visual hierarchy**: Steps are numbered and visually distinct with clear hierarchy ## Composition - Compose with **Message** — Reasoning is typically displayed before or within an assistant's message to show thought process ```tsx Message component can contain Reasoning to show the AI's thinking before the final response ``` - Compose with **ToolCall** — Reasoning often precedes tool calls to explain why a tool is being used ```tsx Reasoning explains the decision to use a tool, ToolCall shows the actual tool invocation ``` - Related: Message, ToolCall, Conversation --- # Response Streaming-optimized markdown renderer for AI responses with GFM support, streaming-safe repair of incomplete syntax, and highlighted code blocks with copy. > Import: `import { Response } from '@slipstream-ui/ai'` > Registry: https://slipstreamui.com/registry/response.json > Tier: molecule · Package: @slipstream-ui/ai ## Design intent Render AI output as rich content without flicker or broken partial syntax while tokens arrive. ## Props | Prop | Type | Default | Required | Description | |---|---|---|---|---| | children | `string` | — | yes | Markdown content to render. | | parseIncompleteMarkdown | `boolean` | `true` | no | Close unclosed emphasis/inline-code/fences during streaming. | ## Examples ### Basic response ```tsx {assistantMessage.content} ``` ### Inside Message ```tsx {c}} /> ``` ## Anti-patterns - **Do not use Response inside a code fence context** — Response is the top-level renderer; nested Response instances double-parse content. ## Accessibility - **Semantic HTML**: Headings, lists and tables are real elements announced correctly. - **Code blocks**: Routed through CodeBlock with accessible copy button. --- # Search Select-with-search: type to filter a full-width dropdown of options, or arrow through the full set from an empty query. > Import: `import { Search } from '@slipstream-ui/core'` > Registry: https://slipstreamui.com/registry/search.json > Tier: molecule · Package: @slipstream-ui/core ## Design intent A native with flat options, optgroups, a placeholder row and native multi-select. > Import: `import { Select } from '@slipstream-ui/core'` > Registry: https://slipstreamui.com/registry/select.json > Tier: atom · Package: @slipstream-ui/core ## Design intent Native selects keep platform keyboard, mobile picker and screen-reader behavior for free. Groups cover coarse categorization, placeholder renders the 'choose one' affordance, and multiple switches the contract to string[] for tag-picker use cases without reimplementing a listbox. ## Props | Prop | Type | Default | Required | Description | |---|---|---|---|---| | options | `SelectOption[]` | — | no | Flat options ({ value, label, disabled? }). Ignored when groups is provided. | | label | `string` | — | no | Visible label rendered and associated via htmlFor/aria | | value | `string | string[]` | — | no | Controlled value (string, or string[] when multiple). | | defaultValue | `string | string[]` | — | no | Initial value when uncontrolled. | | onChange | `(value: string | string[]) => void` | — | no | Fired with the new value; string[] when multiple. | | groups | `SelectOptionGroup[]` | — | no | Optgroups: [{ label, options }] rendered with a heading per section. | | placeholder | `string` | — | no | Renders a disabled empty option as the 'choose one' affordance. | | multiple | `boolean` | `false` | no | Native multi-select; value/defaultValue/onChange switch to string[]. | | onValueChange | `(value: string | string[]) => void` | — | no | Alias for onChange — value-based callback. | ## Examples ### Grouped options Optgroups with a placeholder row. ```tsx ``` ### Controlled select Keep the selected value in state and render it back through value. ```tsx const [size, setSize] = useState('default'); cannot render rich option content. SelectMenu supplies a real listbox with the button/listbox keyboard model while keeping the same value/onValueChange contract as Select, so teams can move between the two without rewriting state. ## Props | Prop | Type | Default | Required | Description | |---|---|---|---|---| | items | `SelectMenuItem[]` | — | yes | Options: { value, label, description?, icon?, disabled?, group? }. | | value | `string | string[]` | — | no | Controlled value(s); string[] when multiple. | | defaultValue | `string | string[]` | — | no | Initial value(s) when uncontrolled. | | onValueChange | `(value: string | string[]) => void` | — | no | Fired with the new selection. | | multiple | `boolean` | `false` | no | Allow several selections; the listbox stays open. | | placeholder | `string` | `Select…` | no | Shown when nothing is selected. | | name | `string` | — | no | Renders hidden form inputs for the selected values. | | renderValue | `(selected: SelectMenuItem[]) => ReactNode` | — | no | Custom trigger content. | | renderItem | `(item, state: { selected: boolean; active: boolean }) => ReactNode` | — | no | Custom option row. | | emptyText | `string` | `No options` | no | Shown when items is empty. | ## Examples ### Rich options Descriptions and grouped headings inside a real listbox. ```tsx ``` ### Multi-select with form input Hidden inputs make the selection submit with the form. ```tsx ``` ## Anti-patterns - **Don't use it for free-text entry** — SelectMenu has no text input. Use Autocomplete when typing a value is expected. - **Don't render more than ~50 options** — There is no filtering. Large sets need Autocomplete or a searchable flow. ## Accessibility - **Keyboard model**: Arrows move the active option, Home/End jump, Enter/Space select, Escape closes, typeahead jumps by first letters ## Composition - Compose with **FormField** — Wrap for label/hint/error wiring ```tsx ``` - Compose with **Select** — Prefer Select when options are plain text (native pickers, mobile UX) ```tsx

```

### With label and helper text

Labelled textarea with a hint

```tsx
<div className="space-y-1">
  <Label htmlFor="bio">Bio</Label>
  <Textarea id="bio" maxLength={280} />
  <p className="text-xs text-muted-foreground">Up to 280 characters</p>
</div>
```

## Anti-patterns

- **Don't use Textarea for single-line values** — Use Input for emails, names, and other short single-line data.
- **Don't use Textarea for rich text** — Textarea is plain text. Use a rich-text editor when formatting is required.

## Accessibility

- **Native semantics**: Wraps textarea; multiline text entry and form validation work natively
- **Character limits**: maxLength is supported natively

## Composition

- Compose with **Label** — Pair with Label for accessibility
  
  ```tsx
  <Label htmlFor="m">Message</Label><Textarea id="m" />
  ```
- Related: Input, Label

---

# TimePicker

Native time field with an HH:MM contract and an optional clear button.

> Import: `import { TimePicker } from '@slipstream-ui/core'`
> Registry: https://slipstreamui.com/registry/time-picker.json
> Tier: molecule · Package: @slipstream-ui/core

## Design intent

Like DatePicker: the platform time control is already accessible and locale-aware. TimePicker standardizes the HH:MM contract and clear affordance.

## Props

| Prop | Type | Default | Required | Description |
|---|---|---|---|---|
| value | `string` | — | no | "HH:MM" (24h), controlled. |
| defaultValue | `string` | — | no | "HH:MM", initial value. |
| onValueChange | `(value: string) => void` | — | no | Fired with the time string; '' when cleared. |
| clearable | `boolean` | `false` | no | Shows a clear button once a value exists. |

## Examples

### Time field

Controlled HH:MM value.

```tsx
<TimePicker aria-label="Starts at" value={start} onValueChange={setStart} clearable />
```

## Anti-patterns

- **Don't mix 12h display with 24h state** — State stays HH:MM; format for display with Intl.

## Accessibility

- **Platform input**: Renders input[type=time]

## Composition

- Compose with **DatePicker** — Pair for date+time scheduling
  
  ```tsx
  <DatePicker aria-label="Date" /><TimePicker aria-label="Time" />
  ```
- Related: DatePicker, FormField, Input

---

# Timeline

Vertical chronology for experience, activity and audit trails, built on an ordered list.

> Import: `import { Timeline } from '@slipstream-ui/core'`
> Registry: https://slipstreamui.com/registry/timeline.json
> Tier: molecule · Package: @slipstream-ui/core

## Design intent

Chronologies communicate order. Rendering them as an ordered list keeps the sequence structural for assistive tech, while the connector rule and dots provide the visual rhythm.

## Props

| Prop | Type | Default | Required | Description |
|---|---|---|---|---|
| items | `{ title: string; period?: string; description?: string; icon?: ReactNode; muted?: boolean }[]` | — | yes | Ordered timeline entries. |

## Examples

### Experience

Period label, title and supporting line per entry.

```tsx
<Timeline
  items={[
    { title: 'Senior Engineer', period: '2023 — Present', description: 'Platform team' },
    { title: 'Engineer', period: '2020 — 2023' },
  ]}
/>
```

## Anti-patterns

- **Don't reverse the DOM order for newest-first** — Reverse the array instead so reading order matches visual order.

## Accessibility

- **Sequence**: Ordered list semantics

## Composition

- Compose with **Card** — Often embedded in profile/about cards
  
  ```tsx
  <Card><CardContent><Timeline items={roles} /></CardContent></Card>
  ```
- Related: List, Card, Separator

---

# Toast

Accessible notifications: tree-scoped provider/hook plus an imperative toast() API rendered by <Toaster />.

> Import: `import { ToastProvider } from '@slipstream-ui/core'`
> Registry: https://slipstreamui.com/registry/toast.json
> Tier: molecule · Package: @slipstream-ui/core

## Design intent

Toasts announce status changes without stealing focus. The provider/useToast pair covers tree-scoped usage; the module-level toast() + <Toaster /> covers event handlers and data layers where threading a hook is impossible (e.g. 1000+ call sites). A polite live region and auto-dismiss keep the queue quiet.

## Props

| Prop | Type | Default | Required | Description |
|---|---|---|---|---|
| title | `string` | — | yes | Toast heading. |
| description | `string` | — | no | Supporting line under the title. |
| variant | `'default' | 'success' | 'error' | 'warning' | 'info'` | `default` | no | Status accent (dot + optional rich tint). |
| action | `{ label: string; onClick: () => void }` | — | no | Single inline action; dismisses the toast after running. |
| duration | `number` | `5000` | no | Auto-dismiss delay in ms; 0 keeps the toast until dismissed. |
| position | `'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'` | `bottom-right` | no | Toaster placement (Toaster component). |
| richColors | `boolean` | `false` | no | Tint the toast surface with its status color (Toaster component). |
| label | `string` | `Notifications` | no | Accessible name of the live region (Toaster component). |

## Examples

### Imperative API

Fire from event handlers or data layers — no hook needed.

```tsx
import { Toaster, toast } from '@slipstream-ui/core';

toast.success('Saved', 'Your changes are live');
toast.error('Upload failed', 'Check your connection');
toast({ title: 'Heads up', duration: 0 });
```

### Tree-scoped provider

Existing provider/hook pair for component-scoped usage.

```tsx
<ToastProvider>
  <App />
</ToastProvider>;

const { toast, dismiss } = useToast();
toast({ title: 'Saved' });
```

## Anti-patterns

- **Do not use toasts for critical errors** — Auto-dismissed messages can be missed. Render persistent inline error states (role=alert) for failures the user must resolve.

## Accessibility

- **Polite live region**: Each toast renders role=status inside a labelled list; announcements never steal focus
- **Dismiss control**: Every toast has a labelled dismiss button (Dismiss <title>)
- **Auto-dismiss timing**: 5s default; duration 0 keeps sticky toasts

## Composition

- Compose with **Toaster** — Mount once near the app root next to your router; keep it outside transforms so fixed positioning is not affected
  
  ```tsx
  <App><Toaster /></App>
  ```
- Compose with **ToastProvider** — Use the provider/hook pair when the call site is inside the React tree
  
  ```tsx
  <ToastProvider><App /></ToastProvider>
  ```
- Related: Confirmation, Button

---

# ToolCall

A component for displaying AI tool/function calls with status, arguments, and results

> Import: `import { ToolCall } from '@slipstream-ui/ai'`
> Registry: https://slipstreamui.com/registry/tool-call.json
> Tier: molecule · Package: @slipstream-ui/ai

## Design intent

The ToolCall component visualizes when an AI agent uses tools or functions. It shows the tool name, status (pending, running, completed, failed), arguments passed, and the result returned. This provides transparency into the AI's actions.

## Props

| Prop | Type | Default | Required | Description |
|---|---|---|---|---|
| toolCall | `ToolCall` | — | yes | The tool call object containing name, arguments, status, and result |
| showResult | `boolean` | `true` | no | Whether to display the tool result |
| className | `string` | — | no | Additional CSS classes to apply |
| labels | `{ pending?: string; running?: string; completed?: string; failed?: string; arguments?: string; result?: string; error?: string }` | — | no | Localized status and section labels. |

## Examples

### Completed tool call

Tool call that completed successfully with result

```tsx
<ToolCall 
  toolCall={{
    id: '1',
    name: 'search',
    arguments: { query: 'React components' },
    status: 'completed',
    result: { results: [...] }
  }}
/>
```

### Running tool call

Tool call currently in progress

```tsx
<ToolCall 
  toolCall={{
    id: '2',
    name: 'calculate',
    arguments: { expression: '2 + 2' },
    status: 'running'
  }}
/>
```

### Failed tool call

Tool call that failed with error message

```tsx
<ToolCall 
  toolCall={{
    id: '3',
    name: 'api_request',
    arguments: { endpoint: '/users' },
    status: 'failed',
    result: { error: 'Timeout' }
  }}
/>
```

### Without result

Tool call with result hidden

```tsx
<ToolCall 
  toolCall={toolCall}
  showResult={false}
/>
```

## Anti-patterns

- **Don't show tool calls for simple operations** — Tool calls should be shown for meaningful operations, not trivial ones.
- **Don't expose sensitive data in arguments** — Never display sensitive credentials or personal data in tool call arguments.
- **Don't ignore failed tool calls** — Failed tool calls should be clearly indicated with error information.

## Accessibility

- **Status indication**: Status is shown with both color and text label for clarity
- **Code readability**: Arguments and results are displayed in pre/code blocks with proper formatting
- **Structure**: Tool call information is organized in clear sections (header, arguments, result)

## Composition

- Compose with **Message** — ToolCall components are typically displayed within assistant messages to show tool usage
  
  ```tsx
  Message component can contain ToolCall to show when the AI used tools during its response
  ```
- Compose with **Reasoning** — Reasoning often precedes ToolCall to explain why a tool is being invoked
  
  ```tsx
  Reasoning explains the decision to use a tool, ToolCall shows the actual invocation
  ```
- Related: Message, Reasoning, Conversation

---

# Tooltip

Hover/focus tooltip with aria-describedby association, delay, and Escape dismissal

> Import: `import { Tooltip } from '@slipstream-ui/core'`
> Registry: https://slipstreamui.com/registry/tooltip.json
> Tier: molecule · Package: @slipstream-ui/core

## Design intent

Tooltip provides supplementary context on hover and keyboard focus. It appears with a short delay, is announced via aria-describedby, and dismisses on Escape so it never traps the user.

## Props

| Prop | Type | Default | Required | Description |
|---|---|---|---|---|
| content | `string` | — | yes | The tooltip text |
| side | `'top' | 'bottom' | 'left' | 'right'` | `top` | no | Placement relative to the trigger |
| delay | `number` | `300` | no | Delay before showing on hover, in milliseconds |
| children | `ReactNode` | — | yes | The trigger element |
| className | `string` | — | no | Additional CSS classes to apply |

## Examples

### Button with tooltip

Supplementary hint on a button

```tsx
<Tooltip content="Save your changes">
  <Button>Save</Button>
</Tooltip>
```

### Custom placement

Tooltip placed to the right with a short delay

```tsx
<Tooltip content="Opens in a new tab" side="right" delay={100}>
  <a href="/docs">Docs</a>
</Tooltip>
```

## Anti-patterns

- **Don't put essential information only in a tooltip** — Tooltips are unavailable on touch devices and to keyboard users in some contexts. Required information must be visible in the UI.
- **Don't use tooltips for interactive content** — Tooltip content is not focusable; use a Popover for links or buttons inside the hint.

## Accessibility

- **aria-describedby association**: The tooltip id is linked to the trigger when visible
- **Keyboard focus support**: Shows on focus as well as hover
- **Escape dismissal**: Escape hides the tooltip without moving focus

## Composition

- Compose with **Button / IconButton** — Wrap icon-only buttons with a Tooltip to name them
  
  ```tsx
  <Tooltip content="Close"><Button aria-label="Close">×</Button></Tooltip>
  ```
- Related: Button, Label