# drift-ui: full usage docs

> A shadcn-compatible component registry. Tags input, stepper, tree view, file dropzone and more, built on Radix or Base UI with Tailwind v4 and installed with the shadcn CLI.

## Setup

Install components from the drift-ui registry into this project.

drift-ui is a shadcn-compatible component registry built on Radix or Base UI with Tailwind v4. Read https://drift-ui.dev/llms.txt for the component list and https://drift-ui.dev/llms-full.txt for props and usage examples before writing code.

1. Make sure the project uses shadcn. If there is no components.json, run `npx shadcn@latest init` and accept the defaults that match the project.
2. Register the namespace: `npx shadcn@latest registry add @drift-ui=https://drift-ui.dev/r/{style}/{name}.json`. The CLI fills in {style} from components.json, so a `base-` style gets the Base UI build and any other style gets Radix.
3. Choose the components this task needs from llms.txt and install them, for example `npx shadcn@latest add @drift-ui/tags-input @drift-ui/stepper`. The CLI also installs their registry and npm dependencies.
4. Import them from the project's ui alias, usually @/components/ui/<name>. Compose them in feature code rather than editing the installed files, and keep the project's existing theme tokens.
5. Run the project's typecheck and lint, then list the components you installed and where you used them.

Optional: `npx shadcn@latest mcp init --client <client>` (claude, cursor, vscode, codex or opencode) lets you search and install from the registry over MCP.

## Conventions

- Every component is a plain file in the project after install, with data-slot attributes on each part and className forwarded through cn().
- Inputs follow one state pattern: value + onValueChange for controlled use, defaultValue for uncontrolled use.
- Colors, radius and focus rings come from the shadcn CSS variables (--primary, --border, --ring and so on), so the project's theme applies automatically.

## Avatar (@drift-ui/avatar)

An image with a fallback for when it fails to load.

Install: `npx shadcn@latest add @drift-ui/avatar`
Source: https://drift-ui.dev/r/avatar.json
Depends on: utils, radix-ui

Identical API to the shadcn/ui component of the same name. Skip it if the project already has one.

## Avatar Group (@drift-ui/avatar-group)

Stacked avatars with presence dots and a +N overflow that lists the rest.

Install: `npx shadcn@latest add @drift-ui/avatar-group`
Source: https://drift-ui.dev/r/avatar-group.json
Depends on: utils, avatar, popover

AvatarGroup stacks AvatarGroupItem children with overlap. max shows that many avatars and turns the rest into a +N button that opens a popover listing them by name. AvatarGroupItem takes name (required, used for initials, the title tooltip and the screen reader label), src and status (online, away, busy or offline) for a presence dot. Built on the shadcn avatar and popover primitives. Pass aria-label to the group.

```tsx
import { AvatarGroup, AvatarGroupItem } from "@/components/ui/avatar-group"

export function Assignees({ users }: { users: { id: string; name: string; image?: string }[] }) {
  return (
    <AvatarGroup aria-label="Assignees" max={4}>
      {users.map((user) => (
        <AvatarGroupItem key={user.id} name={user.name} src={user.image} status="online" />
      ))}
    </AvatarGroup>
  )
}
```

### AvatarGroup

Stacks its AvatarGroupItem children with overlap. Avatars past max collapse into a +N button that opens a popover listing them. Pass aria-label.

- `max` (`number`): Most avatars shown before the +N button.
Other props go to the <div>.

### AvatarGroupItem

One avatar built on the shadcn Avatar, with initials as the fallback and an optional presence dot.

- `name` (`string`, required): Used for the initials, the tooltip and the screen reader label.
- `src` (`string`): Image URL.
- `status` (`"online" | "away" | "busy" | "offline"`): Adds a presence dot and reads the status aloud.
Other props go to the <span>.

## Bulk Action Bar (@drift-ui/bulk-action-bar)

A floating toolbar for acting on selected rows. Escape clears the selection.

Install: `npx shadcn@latest add @drift-ui/bulk-action-bar`
Source: https://drift-ui.dev/r/bulk-action-bar.json
Depends on: utils, button, radix-ui, lucide-react, motion, class-variance-authority

Floating toolbar (Radix or Base UI) that animates in when selectedCount > 0. Props: selectedCount, onClear (also bound to Escape), placement: 'viewport' (portaled, default) or 'container' (absolute inside a relative parent). Put BulkActionBarButton children inside. Requires the motion package.

```tsx
import { BulkActionBar, BulkActionBarButton } from "@/components/ui/bulk-action-bar"

export function FileActions({ selected, onClear }: { selected: string[]; onClear: () => void }) {
  return (
    <BulkActionBar selectedCount={selected.length} onClear={onClear}>
      <BulkActionBarButton>Move</BulkActionBarButton>
      <BulkActionBarButton variant="destructive">Delete</BulkActionBarButton>
    </BulkActionBar>
  )
}
```

### BulkActionBar

A floating toolbar that springs in while something is selected. Put BulkActionBarButton children inside. Needs the motion package.

- `selectedCount` (`number`, required): Number of selected items. The bar shows while it is above 0.
- `onClear` (`() => void`, required): Called by the clear button and by Escape.
- `placement` (`"viewport" | "container"`, default `"viewport"`): viewport portals the bar to the bottom of the screen, container positions it inside the nearest relative parent.
- `aria-label` (`string`, default `"Bulk actions"`): Name of the toolbar.
Other props go to the Toolbar root.

### BulkActionBarButton

A Button that joins the toolbar's arrow key navigation.

- `variant` (`Button variant`, default `"ghost"`): Button style.
- `size` (`Button size`, default `"sm"`): Button size.
Other props go to the Button.

## Color Picker (@drift-ui/color-picker)

Saturation area, hue and alpha sliders, eyedropper, hex input and an oklch readout.

Install: `npx shadcn@latest add @drift-ui/color-picker`
Source: https://drift-ui.dev/r/color-picker.json
Depends on: utils, button, input, popover, @drift-ui/use-controllable-state, radix-ui, lucide-react

Popover picker with a saturation and brightness area, hue and alpha sliders, hex input, oklch readout and the native EyeDropper where supported. Value is a hex string (#rrggbb or #rrggbbaa). Props: value/defaultValue/onValueChange, showAlpha, swatches.

```tsx
import { ColorPicker } from "@/components/ui/color-picker"

export function BrandColorField() {
  return <ColorPicker aria-label="Brand color" defaultValue="#6366f1" swatches={["#0f172a", "#6366f1", "#10b981"]} />
}
```

### ColorPicker

A trigger button that opens a saturation and brightness area, hue and alpha sliders, a hex field, an oklch readout and, where the browser has it, the EyeDropper.

- `value` (`string`): Controlled hex color, "#rrggbb" or "#rrggbbaa".
- `defaultValue` (`string`, default `"#000000"`): Initial value when uncontrolled.
- `onValueChange` (`(hex: string) => void`): Called with the new hex color.
- `showAlpha` (`boolean`, default `true`): Show the opacity slider.
- `swatches` (`string[]`): Preset hex colors shown as buttons.
- `variant` (`Button variant`, default `"outline"`): Style of the trigger button.
- `size` (`Button size`): Size of the trigger button.
Other props go to the trigger <button>.

## Date-Time Range (@drift-ui/date-time-range)

A date range picker with start and end times.

Install: `npx shadcn@latest add @drift-ui/date-time-range`
Source: https://drift-ui.dev/r/date-time-range.json
Depends on: utils, button, input, label, calendar, popover, lucide-react, react-day-picker

DateTimeRangePicker with value/defaultValue of { from?: Date, to?: Date } and onValueChange. Start and end times default to 09:00 and 17:00 and are edited in the popover. Installs the shadcn calendar and popover. Props: locale, placeholder, numberOfMonths, disabled, id.

```tsx
import { DateTimeRangePicker } from "@/components/ui/date-time-range"

export function MaintenanceWindowField() {
  return <DateTimeRangePicker id="maintenance-window" placeholder="Pick a maintenance window" />
}
```

### DateTimeRangePicker

A popover with a range calendar and start and end time inputs. Times default to 09:00 and 17:00.

- `value` (`{ from?: Date; to?: Date }`): Controlled range.
- `defaultValue` (`{ from?: Date; to?: Date }`, default `{}`): Initial value when uncontrolled.
- `onValueChange` (`(range: { from?: Date; to?: Date }) => void`): Called when a day or time changes.
- `locale` (`string`): Locale for the trigger label.
- `placeholder` (`string`, default `"Pick a date range"`): Trigger text while no range is set.
- `numberOfMonths` (`number`, default `2`): Months shown side by side.
- `disabled` (`boolean`): Disables the trigger.
- `id` (`string`): Id of the trigger, so a Label can point at it.
- `className` (`string`): Classes for the trigger.

## Description List (@drift-ui/description-list)

Key and value rows for detail pages, with copy buttons and inline editing.

Install: `npx shadcn@latest add @drift-ui/description-list`
Source: https://drift-ui.dev/r/description-list.json
Depends on: utils, @drift-ui/inline-edit, @drift-ui/use-copy-to-clipboard, lucide-react

DescriptionList renders a <dl> grid and DescriptionItem renders one label and value row. copyable adds a copy button for the value. editable turns string children into an InlineEdit that calls onValueChange(value), which may return a promise; the parent re-renders with the new text, so keep the value in state. Pass a string label so buttons get names like "Copy ID".

```tsx
"use client"

import { useState } from "react"
import { DescriptionItem, DescriptionList } from "@/components/ui/description-list"

export function UserDetails() {
  const [owner, setOwner] = useState("Ana Lima")
  return (
    <DescriptionList>
      <DescriptionItem label="ID" copyable>usr_8f2a</DescriptionItem>
      <DescriptionItem label="Owner" editable onValueChange={setOwner}>{owner}</DescriptionItem>
    </DescriptionList>
  )
}
```

### DescriptionList

A two column <dl> grid for DescriptionItem rows.
Other props go to the <dl>.

### DescriptionItem

One label and value row. The value is the children, so editable rows take a string and the parent stores the edits.

- `label` (`ReactNode`, required): The term. A string label also names the copy and edit buttons.
- `copyable` (`boolean`): Adds a button that copies the value text.
- `editable` (`boolean`): Edits the string children in place with InlineEdit.
- `onValueChange` (`(value: string) => void | Promise<void>`): Called with the edited text. A pending promise keeps the field read-only and a rejection keeps it open.
- `placeholder` (`string`): Shown by an editable row while its value is empty.
Other props go to the <div>.

## Diff Viewer (@drift-ui/diff-viewer)

Side-by-side or unified text diff with word-level highlights and collapsed unchanged regions.

Install: `npx shadcn@latest add @drift-ui/diff-viewer`
Source: https://drift-ui.dev/r/diff-viewer.json
Depends on: utils, lucide-react

Compares two strings line by line with no dependencies. mode is split (default) or unified, and the component holds no mode state, so a mode switch belongs to the parent. Replaced lines that share a word get word-level highlights in ins and del elements. Runs of unchanged lines beyond contextLines (default 3) collapse behind a Show N unchanged lines button that stays in place as Hide once open, so keyboard focus stays on it. Added lines use the chart-2 token and removed lines use destructive; every changed line also has a + or - sign and screen reader text, so color is not the only signal. Past 2000 edits the middle of the text is shown as one full replacement, which keeps two unrelated large inputs from using unbounded memory. Pass aria-label to name the table.

```tsx
import { DiffViewer } from "@/components/ui/diff-viewer"

export function RevisionDiff({ before, after }: { before: string; after: string }) {
  return (
    <DiffViewer
      aria-label="Changes to billing.yaml"
      oldValue={before}
      newValue={after}
      mode="unified"
      contextLines={2}
    />
  )
}
```

### DiffViewer

A line diff of two strings with word-level highlights inside replaced lines. Unchanged runs collapse behind a button that expands them in place.

- `oldValue` (`string`, required): The text before the change.
- `newValue` (`string`, required): The text after the change.
- `mode` (`"split" | "unified"`, default `"split"`): Two columns side by side, or one column.
- `contextLines` (`number`, default `3`): Unchanged lines kept visible next to each change.
Other props go to the <div>.

## Emoji Picker (@drift-ui/emoji-picker)

Searchable emoji grid with categories, skin tones, recently used emoji and arrow-key navigation. Emoji data loads on demand.

Install: `npx shadcn@latest add @drift-ui/emoji-picker`
Source: https://drift-ui.dev/r/emoji-picker.json
Depends on: utils, input, @drift-ui/use-controllable-state, emojibase-data, lucide-react

An inline panel: it has no trigger, so wrap it in a Popover for a reaction button, and override the border with className if the panel doubles it. onSelect(emoji) receives the emoji string, with the skin tone applied. Emoji data comes from emojibase-data through a dynamic import on first mount (about 100 KB gzipped) and is cached for later mounts. Emoji newer than Emoji 15 are left out so older systems do not show empty boxes. Recent emoji and the skin tone persist in localStorage under drift-ui:emoji-picker; recents appear on the next mount, so the grid never shifts under the pointer. skinTone (0 to 5, 0 is the default yellow) with onSkinToneChange makes the tone controlled, and defaultSkinTone sets it until the user picks one. Keyboard: ArrowDown leaves the search field for the grid, arrow keys move between emoji, ArrowUp from the top row returns to search, Home and End go to the row ends, Ctrl or Cmd with Home or End go to the grid ends, PageUp and PageDown jump between categories, Enter or Space selects, and Enter in the search field selects the first result. Category icons are pointer shortcuts, hidden from the keyboard and screen readers because PageUp and PageDown do the same job.

```tsx
import { EmojiPicker } from "@/components/ui/emoji-picker"
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover"

export function ReactionButton({ onReact }: { onReact: (emoji: string) => void }) {
  return (
    <Popover>
      <PopoverTrigger>Add reaction</PopoverTrigger>
      <PopoverContent className="w-auto p-0">
        <EmojiPicker aria-label="Add a reaction" onSelect={onReact} className="border-0" />
      </PopoverContent>
    </Popover>
  )
}
```

### EmojiPicker

An inline emoji panel with search, categories, skin tones and recently used emoji. Data loads on first mount, and recents and the skin tone persist in localStorage.

- `onSelect` (`(emoji: string) => void`): Called with the chosen emoji, skin tone applied.
- `skinTone` (`0 | 1 | 2 | 3 | 4 | 5`): Controlled skin tone. 0 is the default yellow.
- `defaultSkinTone` (`0 | 1 | 2 | 3 | 4 | 5`, default `0`): Tone to use until the user picks one.
- `onSkinToneChange` (`(skinTone: 0 | 1 | 2 | 3 | 4 | 5) => void`): Called when the user picks a skin tone.
Other props go to the <div>.

## File Dropzone (@drift-ui/file-dropzone)

Drag and drop upload with validation, progress and rejection states.

Install: `npx shadcn@latest add @drift-ui/file-dropzone`
Source: https://drift-ui.dev/r/file-dropzone.json
Depends on: utils, lucide-react

FileDropzone validates accept (extensions, MIME types, image/*), maxSize in bytes and maxFiles, then calls onFilesAccepted(files) and onFilesRejected(rejections) where each rejection has { file, reason: 'type' | 'size' | 'count' }. It does not upload or store files: keep the list in your own state and render FileDropzoneList > FileDropzoneItem(name, size, progress?, error?, onRemove?). formatBytes is exported.

```tsx
"use client"

import { useState } from "react"
import { FileDropzone, FileDropzoneItem, FileDropzoneList } from "@/components/ui/file-dropzone"

export function AttachmentsField() {
  const [files, setFiles] = useState<File[]>([])

  return (
    <div className="grid gap-3">
      <FileDropzone accept=".pdf,image/*" maxSize={10 * 1024 * 1024} onFilesAccepted={(added) => setFiles((current) => [...current, ...added])} />
      <FileDropzoneList>
        {files.map((file) => (
          <FileDropzoneItem key={file.name} name={file.name} size={file.size} onRemove={() => setFiles((current) => current.filter((item) => item !== file))} />
        ))}
      </FileDropzoneList>
    </div>
  )
}
```

### FileDropzone

Validates dropped or picked files and reports them. It does not upload or store anything, so keep the list in your own state.

- `accept` (`string`): Comma separated extensions, MIME types or wildcards such as image/*.
- `maxSize` (`number`): Largest file in bytes.
- `maxFiles` (`number`): Most files accepted from one drop or pick.
- `multiple` (`boolean`, default `true`): Allow more than one file at a time.
- `disabled` (`boolean`): Ignore drops and clicks.
- `onFilesAccepted` (`(files: File[]) => void`): Called with the files that passed validation.
- `onFilesRejected` (`(rejections: FileRejection[]) => void`): Called with { file, reason } for each rejected file, where reason is "type", "size" or "count".
Other props go to the <label>.

### FileDropzoneItem

One row of a FileDropzoneList. A progress bar shows while progress is below 100.

- `name` (`string`, required): File name.
- `size` (`number`, required): File size in bytes.
- `progress` (`number`): Upload progress from 0 to 100.
- `error` (`string`): Marks the row invalid and shows the message.
- `onRemove` (`() => void`): Shows a remove button that calls it.
Other props go to the <li>.

## Filter Builder (@drift-ui/filter-builder)

Field, operator and value filter chips with a matchesFilter helper for your rows.

Install: `npx shadcn@latest add @drift-ui/filter-builder`
Source: https://drift-ui.dev/r/filter-builder.json
Depends on: utils, button, input, popover, @drift-ui/use-controllable-state, radix-ui, lucide-react

Chip based filters. fields: FilterField[] with { id, label, type: 'text' | 'number' | 'select', options? }. Value is Filter[] ({ id, fieldId, operator, value }). Use matchesFilter(fieldValue, filter) from @/lib/filter to apply filters to your rows.

```tsx
"use client"

import { useState } from "react"
import { FilterBuilder } from "@/components/ui/filter-builder"
import { matchesFilter, type Filter, type FilterField } from "@/lib/filter"

const fields: FilterField[] = [
  { id: "status", label: "Status", type: "select", options: [{ value: "open", label: "Open" }, { value: "closed", label: "Closed" }] },
  { id: "title", label: "Title", type: "text" },
]

export function IssueFilters({ issues }: { issues: { status: string; title: string }[] }) {
  const [filters, setFilters] = useState<Filter[]>([])
  const visible = issues.filter((issue) => filters.every((filter) => matchesFilter(issue[filter.fieldId as "status" | "title"], filter)))

  return (
    <div className="grid gap-3">
      <FilterBuilder fields={fields} value={filters} onValueChange={setFilters} />
      <p className="text-sm text-muted-foreground">{visible.length} issues</p>
    </div>
  )
}
```

### FilterBuilder

A row of filter chips with an Add filter menu. Each chip edits its operator and value in place.

- `fields` (`FilterField[]`, required): Filterable fields: { id, label, type: "text" | "number" | "select", options?, icon? }.
- `value` (`Filter[]`): Controlled filters.
- `defaultValue` (`Filter[]`, default `[]`): Initial value when uncontrolled.
- `onValueChange` (`(filters: Filter[]) => void`): Called when a filter is added, changed or removed.
- `aria-label` (`string`, default `"Filters"`): Name of the filter group.
Other props go to the <div>.

### matchesFilter

`matchesFilter(fieldValue: string | number, filter: Filter): boolean`

Import from @/lib/filter to apply a Filter ({ id, fieldId, operator, value }) to your rows. An empty filter value matches everything. Text fields use contains, not-contains, is and is-not, numbers use eq, gt and lt, and selects use is and is-not.

## Inline Edit (@drift-ui/inline-edit)

Click to edit text in place. Enter saves, Escape cancels, async saves supported.

Install: `npx shadcn@latest add @drift-ui/inline-edit`
Source: https://drift-ui.dev/r/inline-edit.json
Depends on: utils, lucide-react

Click to edit, Enter or blur saves, Escape cancels. value is required and onSave(value) may return a promise; while it is pending the field is read only, and a rejected promise marks it invalid and keeps it open. Pass aria-label describing the field.

```tsx
"use client"

import { useState } from "react"
import { InlineEdit } from "@/components/ui/inline-edit"

export function ProjectName() {
  const [name, setName] = useState("Billing migration")
  return <InlineEdit aria-label="Project name" value={name} onSave={setName} />
}
```

### InlineEdit

Text that turns into an input on click. Enter or blur saves and Escape cancels. Pass aria-label to describe the field.

- `value` (`string`, required): The saved text.
- `onSave` (`(value: string) => void | Promise<void>`, required): Called with the edited text. While a returned promise is pending the field is read-only, and a rejection marks it invalid and keeps it open.
- `placeholder` (`string`, default `"Empty"`): Text shown while value is empty.
- `disabled` (`boolean`): Prevents editing.
Other props go to the <div>.

## JSON Viewer (@drift-ui/json-viewer)

Collapsible, searchable JSON with typed colors, copy value or path, and chunked large arrays.

Install: `npx shadcn@latest add @drift-ui/json-viewer`
Source: https://drift-ui.dev/r/json-viewer.json
Depends on: utils, input, @drift-ui/tree-view, @drift-ui/use-copy-to-clipboard, lucide-react

Read-only JSON tree built on tree-view, so arrow keys, Home, End and typeahead work. defaultExpandDepth (default 1) opens that many levels. Strings, numbers and booleans use the chart-2, chart-1 and chart-3 tokens mixed with foreground for readable contrast, and null uses muted text. The search field highlights matching keys and values and opens their parents. Each row has pointer-only copy value and copy path buttons, shown on hover or always on touch screens; from the keyboard, Ctrl or Cmd+C copies the focused value and Shift+Ctrl or Cmd+C copies its path, like users[0].name. onCopy(path, value, target) runs after a copy. Arrays over 100 items split into groups of 100 and only open branches render.

```tsx
import { JsonViewer } from "@/components/ui/json-viewer"

export function WebhookPayload({ payload }: { payload: unknown }) {
  return <JsonViewer aria-label="Webhook payload" data={payload} defaultExpandDepth={2} />
}
```

### JsonViewer

A searchable JSON tree on top of TreeView. Rows show copy value and copy path buttons on hover, or always on touch screens; Ctrl or Cmd+C copies the focused value and Shift+Ctrl or Cmd+C its path. Arrays over 100 items open as groups of 100.

- `data` (`unknown`, required): Any JSON value.
- `defaultExpandDepth` (`number`, default `1`): How many levels start open.
- `onCopy` (`(path: string, value: unknown, target: "value" | "path") => void`): Called after a value or path is copied.
Other props go to the <div>.

## Mention Textarea (@drift-ui/mention-textarea)

A textarea that suggests people, channels or anything else after a trigger character.

Install: `npx shadcn@latest add @drift-ui/mention-textarea`
Source: https://drift-ui.dev/r/mention-textarea.json
Depends on: utils, popover, @drift-ui/use-controllable-state, radix-ui

Textarea that opens a suggestion list when the caret follows a trigger character. triggers maps a character to options, for example { '@': people, '#': channels }, each option { value, label, description? }. Selecting inserts trigger + value. Value is plain text with value/defaultValue/onValueChange.

```tsx
import { MentionTextarea } from "@/components/ui/mention-textarea"

const people = [{ value: "noor", label: "Noor Haddad" }, { value: "tomasz", label: "Tomasz Wierzba" }]

export function CommentBox() {
  return <MentionTextarea aria-label="Comment" placeholder="Write a comment" triggers={{ "@": people }} />
}
```

### MentionTextarea

Opens a suggestion list when the caret follows a trigger character. Arrow keys move through it, Enter or Tab inserts the trigger, the option's value and a space, and Escape closes it.

- `value` (`string`): Controlled text.
- `defaultValue` (`string`, default `""`): Initial value when uncontrolled.
- `onValueChange` (`(value: string) => void`): Called when the text changes.
- `triggers` (`Record<string, MentionOption[]>`, required): Maps a trigger character to its options, for example { "@": people, "#": channels }.
Other props go to the <textarea>.

### MentionOption

One suggestion.

- `value` (`string`, required): Text inserted after the trigger. Typing filters on value and label.
- `label` (`string`, required): Text shown in the list.
- `description` (`string`): Second line under the label.

## Multi Select (@drift-ui/multi-select)

Pick several values from a fixed list, with search, groups, chips and a selection limit.

Install: `npx shadcn@latest add @drift-ui/multi-select`
Source: https://drift-ui.dev/r/multi-select.json
Depends on: utils, badge, popover, @drift-ui/use-controllable-state, radix-ui, lucide-react

Pick several values from a known list. options: { value, label, group? }[]. Controlled with value/onValueChange or uncontrolled with defaultValue, both string[]. Typing filters, Enter toggles the highlighted option, Backspace on an empty field selects then removes the last chip, and a clear button empties the selection. Props: maxSelected (disables unselected options when reached and hides Select all), maxVisibleChips (collapses the rest into +N). Spreads remaining props onto the inner input, so id, placeholder and aria-label work. For free text use tags-input instead.

```tsx
import { Label } from "@/components/ui/label"
import { MultiSelect } from "@/components/ui/multi-select"

const regions = [
  { value: "eu-west-1", label: "Ireland", group: "Europe" },
  { value: "us-east-1", label: "Virginia", group: "Americas" },
]

export function RegionsField() {
  return (
    <div className="grid gap-2">
      <Label htmlFor="regions">Regions</Label>
      <MultiSelect id="regions" options={regions} placeholder="Pick regions" maxVisibleChips={3} />
    </div>
  )
}
```

### MultiSelect

A combobox whose listbox allows several selections. Typing filters, ArrowUp and ArrowDown move through the list, Enter toggles the highlighted option and Escape closes it. Backspace at the start of the field selects the last chip and a second Backspace removes it. A Select all option toggles every matching option when there is no maxSelected.

- `options` (`MultiSelectOption[]`, required): The values to choose from.
- `value` (`string[]`): Controlled list of selected values.
- `defaultValue` (`string[]`, default `[]`): Initial value when uncontrolled.
- `onValueChange` (`(value: string[]) => void`): Called after an option is selected or removed.
- `maxSelected` (`number`): Most values allowed. Unselected options are disabled once it is reached.
- `maxVisibleChips` (`number`): Chips shown before the rest collapse into a +N count.
Other props go to the <input>.

### MultiSelectOption

One choice.

- `value` (`string`, required): Stored in the value array.
- `label` (`string`, required): Text shown in the list and on the chip.
- `group` (`string`): Heading the option is listed under.

## Number Input (@drift-ui/number-input)

A spinbutton with min, max, step and locale formatting.

Install: `npx shadcn@latest add @drift-ui/number-input`
Source: https://drift-ui.dev/r/number-input.json
Depends on: utils, lucide-react

Value is number | null. Props: min, max, step, locale, formatOptions (Intl.NumberFormatOptions, e.g. currency), name (submits the raw number through a hidden input). Arrow keys step, Shift or PageUp/PageDown step by 10x, Home/End jump to min/max. Typed text is parsed with the locale's separators.

```tsx
import { NumberInput } from "@/components/ui/number-input"

export function BudgetField() {
  return (
    <NumberInput
      aria-label="Monthly budget"
      defaultValue={1240.5}
      min={0}
      step={10}
      locale="de-DE"
      formatOptions={{ style: "currency", currency: "EUR" }}
    />
  )
}
```

### NumberInput

Arrow keys step by step, Shift+Arrow and PageUp/PageDown by ten steps, and Home/End jump to min and max. Typed text is parsed with the locale's separators.

- `value` (`number | null`): Controlled number, or null when empty.
- `defaultValue` (`number | null`, default `null`): Initial value when uncontrolled.
- `onValueChange` (`(value: number | null) => void`): Called when the parsed number changes.
- `min` (`number`): Lowest allowed value.
- `max` (`number`): Highest allowed value.
- `step` (`number`, default `1`): Amount the arrow keys add or subtract.
- `locale` (`string`): Locale for formatting and parsing. Defaults to the browser's.
- `formatOptions` (`Intl.NumberFormatOptions`): Display format, for example a currency.
- `name` (`string`): Submits the raw number through a hidden input.
Other props go to the <input>.

## Password Input (@drift-ui/password-input)

A password field with a reveal toggle and a strength meter.

Install: `npx shadcn@latest add @drift-ui/password-input`
Source: https://drift-ui.dev/r/password-input.json
Depends on: utils, input, lucide-react

PasswordInput accepts every input prop except type and adds an accessible reveal toggle. PasswordStrength takes value and renders a 4 segment meter with a polite live region; override scoring with getScore(value) => 0 | 1 | 2 | 3 | 4 and labels with a 5 item tuple.

```tsx
"use client"

import { useState } from "react"
import { PasswordInput, PasswordStrength } from "@/components/ui/password-input"

export function NewPasswordField() {
  const [password, setPassword] = useState("")

  return (
    <div className="grid gap-2">
      <PasswordInput autoComplete="new-password" value={password} onChange={(event) => setPassword(event.target.value)} />
      <PasswordStrength value={password} />
    </div>
  )
}
```

### PasswordInput

A password field with a button that shows and hides the value. It has no props of its own.
Other props go to the <input>, except type.

### PasswordStrength

A four segment meter with a polite live region that announces the label.

- `value` (`string`, required): The password to score.
- `getScore` (`(value: string) => 0 | 1 | 2 | 3 | 4`, default `scorePassword`): Replaces the built-in scoring.
- `labels` (`[string, string, string, string, string]`, default `["Too weak", "Weak", "Fair", "Good", "Strong"]`): Label for each score from 0 to 4.
Other props go to the <div>.

## Rating (@drift-ui/rating)

Pick a score with stars or any icon, in whole or half steps, from the keyboard or pointer.

Install: `npx shadcn@latest add @drift-ui/rating`
Source: https://drift-ui.dev/r/rating.json
Depends on: utils, @drift-ui/use-controllable-state, lucide-react

Radio group of icons for a score. Controlled with value/onValueChange or uncontrolled with defaultValue (0 means no rating). max sets the icon count (default 5), step={0.5} allows half scores, icon swaps the default lucide Star for any SVG icon. Arrow keys change the score, Home and End jump to the ends. readOnly renders a role=img labelled like "3.5 out of 5". The fill color is the root's text color (text-primary), so className="text-chart-4" recolors it. Pass aria-label.

```tsx
"use client"

import { useState } from "react"
import { Rating } from "@/components/ui/rating"

export function ReviewScore() {
  const [score, setScore] = useState(0)
  return <Rating aria-label="Your rating" value={score} onValueChange={setScore} step={0.5} />
}
```

### Rating

A WAI-ARIA radio group of icons. Arrow keys raise or lower the score by one step, Home and End jump to the ends, and hovering previews a score. Pass aria-label.

- `value` (`number`): Controlled score.
- `defaultValue` (`number`, default `0`): Initial value when uncontrolled.
- `onValueChange` (`(value: number) => void`): Called with the new score.
- `max` (`number`, default `5`): Number of icons.
- `step` (`1 | 0.5`, default `1`): 0.5 lets each icon fill by half.
- `icon` (`ReactNode`, default `<StarIcon />`): SVG icon drawn for each point. Filled with the root's text color.
- `readOnly` (`boolean`): Shows the score without radios, as an image labelled like "3.5 out of 5".
- `disabled` (`boolean`): Dims the rating and removes it from the tab order.
Other props go to the <div>.

## Recurrence Editor (@drift-ui/recurrence-editor)

Edit an RRULE repeat rule with a plain-language summary and the next occurrences.

Install: `npx shadcn@latest add @drift-ui/recurrence-editor`
Source: https://drift-ui.dev/r/recurrence-editor.json
Depends on: utils, input, label, @drift-ui/number-input, @drift-ui/use-controllable-state

RecurrenceEditor edits an RFC 5545 RRULE string (without the RRULE: prefix) through value/defaultValue and onValueChange. Supports DAILY, WEEKLY with BYDAY, MONTHLY with BYMONTHDAY or an ordinal BYDAY such as 2TU or -1FR, YEARLY, INTERVAL, COUNT and UNTIL. Pass start (a Date) so weekday, month day and preview line up with the event; showPreview={n} lists the next n occurrences. Pure helpers live in @/lib/recurrence: parseRRule, formatRRule, describeRecurrence and occurrences. Installs number-input.

```tsx
"use client"

import { useState } from "react"
import { RecurrenceEditor } from "@/components/ui/recurrence-editor"

export function StandupRepeat({ start }: { start: Date }) {
  const [rule, setRule] = useState("FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR")

  return <RecurrenceEditor aria-label="Repeat" value={rule} onValueChange={setRule} start={start} showPreview={3} />
}
```

### RecurrenceEditor

Edits an RFC 5545 RRULE: interval and frequency, weekdays for weekly rules, day of the month or ordinal weekday for monthly rules, and an end that is never, a date or a count. Shows a plain-language summary and, optionally, the next occurrences.

- `value` (`string`): Controlled RRULE, such as "FREQ=WEEKLY;BYDAY=TU".
- `defaultValue` (`string`, default `"FREQ=WEEKLY"`): Initial value when uncontrolled.
- `onValueChange` (`(rule: string) => void`): Called with the new RRULE.
- `start` (`Date`, default `today`): First occurrence. Sets the default weekday, month day and time, and where the preview starts.
- `showPreview` (`number`, default `0`): How many upcoming occurrences to list.
Other props go to the <fieldset>.

### parseRRule, formatRRule, describeRecurrence, occurrences

`parseRRule(rule: string): Recurrence; formatRRule(recurrence: Recurrence): string; describeRecurrence(recurrence: Recurrence, start: Date): string; occurrences(recurrence: Recurrence, start: Date, limit: number): Date[]`

Import from @/lib/recurrence to read, write, summarize or expand a rule outside the editor.

## Shortcut Recorder (@drift-ui/shortcut-recorder)

Records a key combination and renders it with platform symbols.

Install: `npx shadcn@latest add @drift-ui/shortcut-recorder`
Source: https://drift-ui.dev/r/shortcut-recorder.json
Depends on: utils, @drift-ui/use-controllable-state

Click to record, then press a combination. Stores a portable string such as 'Mod+Shift+K' where Mod is Cmd on macOS and Ctrl elsewhere. requireModifier defaults to true. ShortcutKeys renders a stored shortcut as kbd elements; matchesShortcut(event, shortcut, isMac) from @/lib/shortcut checks key events.

```tsx
import { ShortcutKeys, ShortcutRecorder } from "@/components/ui/shortcut-recorder"

export function CommandMenuShortcut() {
  return (
    <div className="flex items-center gap-3">
      <ShortcutRecorder aria-label="Command menu shortcut" defaultValue="Mod+K" />
      <ShortcutKeys shortcut="Mod+Shift+P" />
    </div>
  )
}
```

### ShortcutRecorder

Click, then press a combination. The value is portable, such as "Mod+Shift+K", where Mod is Cmd on macOS and Ctrl elsewhere.

- `value` (`string`): Controlled shortcut.
- `defaultValue` (`string`, default `""`): Initial value when uncontrolled.
- `onValueChange` (`(shortcut: string) => void`): Called with the recorded shortcut.
- `placeholder` (`string`, default `"Record shortcut"`): Text while nothing is recorded.
- `requireModifier` (`boolean`, default `true`): Ignore keys pressed without a modifier, except function keys.
Other props go to the <button>.

### ShortcutKeys

Renders a stored shortcut as kbd elements for the current platform.

- `shortcut` (`string`, required): A shortcut string such as "Mod+K".
Other props go to the <span>.

### matchesShortcut

`matchesShortcut(event: KeyboardEvent, shortcut: string, isMac: boolean): boolean`

Import from @/lib/shortcut. Returns true when a keyboard event matches a stored shortcut.

## Sortable List (@drift-ui/sortable-list)

Reorderable list with drag-and-drop and full keyboard accessibility.

Install: `npx shadcn@latest add @drift-ui/sortable-list`
Source: https://drift-ui.dev/r/sortable-list.json
Depends on: utils, @drift-ui/use-controllable-state, lucide-react, motion

Reorderable list built on Motion's Reorder: the dragged row follows the pointer, neighbours spring out of the way, and the page or a scrollable parent scrolls near its edges. Controlled with value/onValueChange or uncontrolled with defaultValue. onValueChange fires once, on drop, and only if the order changed; the render function gets the live index during a move. Space/Enter picks up or drops an item, ArrowUp/ArrowDown (or ArrowLeft/ArrowRight for horizontal) moves it, Home/End jump to the ends, and Escape cancels a keyboard or pointer move. Moving focus away drops the item. Screen readers receive live status announcements. Add SortableDragHandle to limit dragging to a grip, which also leaves touch scrolling and text selection working on the row. Without a handle, the row drags from anywhere except links, buttons and form controls inside it. If the list sits in an overflow container that can scroll, wrap that container in motion.div with layoutScroll.

```tsx
import {
  SortableDragHandle,
  SortableItem,
  SortableList,
} from "@/components/ui/sortable-list"

const tasks = [
  { id: "1", title: "Review pull requests" },
  { id: "2", title: "Update documentation" },
]

export function TaskList() {
  return (
    <SortableList defaultValue={tasks} getKey={(task) => task.id}>
      {(task) => (
        <SortableItem key={task.id} value={task.id}>
          <SortableDragHandle />
          <span>{task.title}</span>
        </SortableItem>
      )}
    </SortableList>
  )
}
```

### SortableList

Reorderable list with drag-and-drop and full keyboard accessibility. Space or Enter picks up and drops an item, arrow keys, Home and End move it, and Escape cancels the move for both keyboard and pointer.

- `value` (`T[]`): Controlled list of items.
- `defaultValue` (`T[]`, default `[]`): Initial value when uncontrolled.
- `onValueChange` (`(items: T[]) => void`): Called once on drop, if the order changed.
- `children` (`(item: T, index: number) => ReactNode`, required): Renders one SortableItem. index follows the live order during a move.
- `getKey` (`(item: T, index: number) => string | number`): Extracts a unique key from each item. Defaults to the item itself for strings and numbers, then item.id, then the index.
- `getItemLabel` (`(item: T, index: number) => string`): Returns an accessible name for screen reader announcements.
- `orientation` (`"vertical" | "horizontal"`, default `"vertical"`): Layout direction and keyboard arrow axis.
- `disabled` (`boolean`): Prevents dragging and keyboard reordering across the list.
Other props go to the <motion.ul>.

### SortableItem

An individual reorderable row. If no SortableDragHandle is present inside, the item itself is draggable and keyboard-interactive, except from links, buttons and form controls inside it. data-grabbed and data-dragging mark the moving row.

- `value` (`string | number`, required): Unique identifier matching the item's key.
- `disabled` (`boolean`): Disables reordering for this specific item.
Other props go to the <motion.li>.

### SortableDragHandle

Optional handle button that restricts dragging and keyboard focus to a grab icon. Its accessible name comes from getItemLabel.
Other props go to the <button>.

## Stepper (@drift-ui/stepper)

Multi-step flows with linear or free navigation.

Install: `npx shadcn@latest add @drift-ui/stepper`
Source: https://drift-ui.dev/r/stepper.json
Depends on: utils, radix-ui, lucide-react

Built on Radix Tabs, or Base UI Tabs from the Base UI registry. Steps are zero-based numbers: value/defaultValue/onValueChange. linear disables steps beyond the furthest one reached. Compose StepperList > StepperItem(step) > StepperTrigger > StepperIndicator + StepperTitle, plus StepperSeparator and StepperContent(step). StepperNext and StepperPrevious support asChild; pass stepCount so Next disables on the last step. useStepper() exposes activeStep and setActiveStep.

```tsx
import { Button } from "@/components/ui/button"
import {
  Stepper, StepperContent, StepperIndicator, StepperItem, StepperList,
  StepperNext, StepperPrevious, StepperSeparator, StepperTitle, StepperTrigger,
} from "@/components/ui/stepper"

const steps = ["Account", "Workspace", "Invite"]

export function OnboardingSteps() {
  return (
    <Stepper linear stepCount={steps.length}>
      <StepperList aria-label="Onboarding">
        {steps.map((title, index) => (
          <StepperItem key={title} step={index}>
            <StepperTrigger>
              <StepperIndicator />
              <StepperTitle>{title}</StepperTitle>
            </StepperTrigger>
            <StepperSeparator />
          </StepperItem>
        ))}
      </StepperList>
      {steps.map((title, index) => (
        <StepperContent key={title} step={index}>{title} form goes here</StepperContent>
      ))}
      <div className="flex justify-between">
        <StepperPrevious asChild><Button variant="outline">Back</Button></StepperPrevious>
        <StepperNext asChild><Button>Continue</Button></StepperNext>
      </div>
    </Stepper>
  )
}
```

### Stepper

Compose StepperList > StepperItem > StepperTrigger > StepperIndicator + StepperTitle, with StepperSeparator between items and a StepperContent for each step. Steps are zero-based.

- `value` (`number`): Controlled step.
- `defaultValue` (`number`, default `0`): Initial value when uncontrolled.
- `onValueChange` (`(step: number) => void`): Called when the step changes.
- `linear` (`boolean`, default `false`): Disable steps past the furthest one reached.
- `stepCount` (`number`): Number of steps, so StepperNext disables on the last one.
- `orientation` (`"horizontal" | "vertical"`, default `"horizontal"`): Layout direction.
Other props go to the Tabs root.

### StepperItem

Wraps one step and sets data-state to "completed", "active" or "upcoming" for its children.

- `step` (`number`, required): The step this item stands for.
Other props go to the <div>.

### StepperContent

Panel shown while its step is active.

- `step` (`number`, required): The step this panel belongs to.
Other props go to the Tabs panel.

### StepperPrevious, StepperNext

Buttons that move one step back or forward. They disable on the first step and, with stepCount, on the last.

- `asChild` (`boolean`, default `false`): Render the child element, such as a Button, instead of a button.
Other props go to the <button>.

### useStepper

`useStepper(): { activeStep: number; setActiveStep: (step: number) => void }`

For custom controls rendered inside Stepper.

## Tags Input (@drift-ui/tags-input)

Type, paste or remove tags with full keyboard support.

Install: `npx shadcn@latest add @drift-ui/tags-input`
Source: https://drift-ui.dev/r/tags-input.json
Depends on: utils, badge, lucide-react

Controlled with value/onValueChange or uncontrolled with defaultValue. Enter or comma adds a tag, Backspace or ArrowLeft with the caret at the start selects a tag (announced to screen readers), a second Backspace removes it, pasting splits on commas, tabs and newlines. Props: max (the field turns read-only when full, so tags stay removable by keyboard), validate(tag) => boolean, allowDuplicates, addOnBlur. Spreads remaining props onto the inner input, so id, placeholder and aria-invalid work.

```tsx
import { Label } from "@/components/ui/label"
import { TagsInput } from "@/components/ui/tags-input"

export function EnvironmentsField() {
  return (
    <div className="grid gap-2">
      <Label htmlFor="environments">Environments</Label>
      <TagsInput id="environments" defaultValue={["staging"]} max={6} placeholder="Add environment" />
    </div>
  )
}
```

### TagsInput

Enter or comma adds a tag. Backspace or ArrowLeft at the start of the field selects the last tag and announces it, and a second Backspace removes it. Pasted text splits on commas, tabs and newlines.

- `value` (`string[]`): Controlled list of tags.
- `defaultValue` (`string[]`, default `[]`): Initial value when uncontrolled.
- `onValueChange` (`(tags: string[]) => void`): Called after a tag is added or removed.
- `max` (`number`): Most tags allowed. When full the field turns read-only, and tags stay removable by keyboard.
- `validate` (`(tag: string) => boolean`): Return false to reject a tag.
- `allowDuplicates` (`boolean`, default `false`): Accept a tag that is already in the list.
- `addOnBlur` (`boolean`, default `false`): Add the typed text as a tag when the field loses focus.
Other props go to the <input>.

## Time Field (@drift-ui/time-field)

Segmented hour, minute and AM/PM spinbuttons with typeahead.

Install: `npx shadcn@latest add @drift-ui/time-field`
Source: https://drift-ui.dev/r/time-field.json
Depends on: utils, @drift-ui/use-controllable-state

Segmented time input with value 'HH:mm' in 24 hour time (empty string when unset). hourCycle 12 adds an AM/PM segment, minuteStep sets the arrow key step, name submits through a hidden input. The root is role=group, so pass aria-label or aria-labelledby.

```tsx
import { TimeField } from "@/components/ui/time-field"

export function StandupTimeField() {
  return <TimeField aria-label="Standup time" defaultValue="09:30" hourCycle={12} minuteStep={15} />
}
```

### TimeField

Segmented hour and minute input. The root has role=group, so pass aria-label or aria-labelledby.

- `value` (`string`): Controlled time as "HH:mm" in 24 hour time.
- `defaultValue` (`string`, default `""`): Initial value when uncontrolled.
- `onValueChange` (`(value: string) => void`): Called with "HH:mm", or an empty string when cleared.
- `hourCycle` (`12 | 24`, default `24`): 12 adds an AM/PM segment.
- `minuteStep` (`number`, default `1`): Amount the arrow keys change the minutes by.
- `name` (`string`): Submits the value through a hidden input.
- `disabled` (`boolean`): Disables every segment.
Other props go to the <div>.

## Timeline (@drift-ui/timeline)

Activity feeds and changelogs with status indicators.

Install: `npx shadcn@latest add @drift-ui/timeline`
Source: https://drift-ui.dev/r/timeline.json
Depends on: utils, class-variance-authority

Presentational and server-component safe. TimelineIndicator takes variant: default | current | success | destructive. Wrap text in TimelineContent, with TimelineHeader holding TimelineTitle and TimelineTime.

```tsx
import {
  Timeline, TimelineContent, TimelineDescription, TimelineHeader,
  TimelineIndicator, TimelineItem, TimelineTime, TimelineTitle,
} from "@/components/ui/timeline"

export function DeployHistory() {
  return (
    <Timeline>
      <TimelineItem>
        <TimelineIndicator variant="current" />
        <TimelineContent>
          <TimelineHeader>
            <TimelineTitle>Deployed to production</TimelineTitle>
            <TimelineTime dateTime="2026-10-27T14:32">14:32</TimelineTime>
          </TimelineHeader>
          <TimelineDescription>v2.14.0 rolled out to 3 replicas.</TimelineDescription>
        </TimelineContent>
      </TimelineItem>
    </Timeline>
  )
}
```

### Timeline

Compose Timeline > TimelineItem > TimelineIndicator + TimelineContent, with TimelineHeader holding TimelineTitle and TimelineTime, then TimelineDescription. Every part spreads its props onto its element, and none needs client JavaScript.
Other props go to the <ol>.

### TimelineIndicator

The dot next to an item.

- `variant` (`"default" | "current" | "success" | "destructive"`, default `"default"`): Color and ring of the dot.
Other props go to the <span>.

## Tour (@drift-ui/tour)

A step-by-step product tour that spotlights real elements on the page.

Install: `npx shadcn@latest add @drift-ui/tour`
Source: https://drift-ui.dev/r/tour.json
Depends on: utils, button, popover, @drift-ui/use-controllable-state, radix-ui, lucide-react

Wrap the page in Tour with steps: TourStep[] ({ target, title, description?, side? }) and mark elements with TourTarget name matching step.target. open/onOpenChange and step/onStepChange are optional controlled props; onComplete fires after the last step. Focus is trapped in the tour card and returns to the opener on close.

```tsx
"use client"

import { useState } from "react"
import { Button } from "@/components/ui/button"
import { Tour, TourTarget, type TourStep } from "@/components/ui/tour"

const steps: TourStep[] = [{ target: "create", title: "Create a project", description: "Start here." }]

export function DashboardTour() {
  const [isOpen, setIsOpen] = useState(false)

  return (
    <Tour steps={steps} open={isOpen} onOpenChange={setIsOpen}>
      <TourTarget name="create"><Button>New project</Button></TourTarget>
      <Button variant="ghost" onClick={() => setIsOpen(true)}>Take the tour</Button>
    </Tour>
  )
}
```

### Tour

Wrap the page in Tour and mark elements with TourTarget. Arrow keys move between steps and Escape ends the tour. Focus stays in the card and returns to the opener when it closes.

- `steps` (`TourStep[]`, required): Steps in order: { target, title, description?, side? }, where side is "top", "right", "bottom" or "left".
- `open` (`boolean`): Controlled open state.
- `defaultOpen` (`boolean`, default `false`): Initial open state when uncontrolled.
- `onOpenChange` (`(open: boolean) => void`): Called when the tour starts or ends.
- `step` (`number`): Controlled zero-based step.
- `defaultStep` (`number`, default `0`): Initial step when uncontrolled.
- `onStepChange` (`(step: number) => void`): Called when the step changes.
- `onComplete` (`() => void`): Called after Finish on the last step.

### TourTarget

Marks its single child as a tour target without adding an element.

- `name` (`string`, required): Matches a step's target.

## Tree View (@drift-ui/tree-view)

An ARIA tree with arrow keys, typeahead, selection and lazy children.

Install: `npx shadcn@latest add @drift-ui/tree-view`
Source: https://drift-ui.dev/r/tree-view.json
Depends on: utils, lucide-react

WAI-ARIA tree driven by an items array of TreeNode { id, label, icon?, children?, isBranch?, disabled?, textValue? }. expanded/onExpandedChange and selected/onSelectedChange are optional controlled props. A node with isBranch: true and children undefined renders a loading row while expanded, so load children in onExpandedChange and update items. Always pass aria-label.

```tsx
import { TreeView, type TreeNode } from "@/components/ui/tree-view"

const items: TreeNode[] = [
  { id: "app", label: "app", children: [{ id: "app/page", label: "page.tsx" }] },
  { id: "archive", label: "archive", isBranch: true },
]

export function ProjectTree() {
  return <TreeView aria-label="Project files" items={items} defaultExpanded={["app"]} />
}
```

### TreeView

A WAI-ARIA tree. Arrow keys move and expand, Home and End jump, Enter or Space selects, and typing jumps to the next matching node. Always pass aria-label.

- `items` (`TreeNode[]`, required): Nodes to render.
- `expanded` (`string[]`): Controlled ids of open branches.
- `defaultExpanded` (`string[]`, default `[]`): Initially open branches when uncontrolled.
- `onExpandedChange` (`(expanded: string[]) => void`): Called when a branch opens or closes. Load lazy children here.
- `selected` (`string | null`): Controlled id of the selected node.
- `defaultSelected` (`string | null`, default `null`): Initially selected node when uncontrolled.
- `onSelectedChange` (`(id: string) => void`): Called when a node is selected.
Other props go to the <ul>.

### TreeNode

One node. A node with isBranch and no children shows a loading row while open, so you can fetch its children in onExpandedChange.

- `id` (`string`, required): Unique id.
- `label` (`ReactNode`, required): Content of the row.
- `textValue` (`string`): Text for typeahead when label is not a string.
- `icon` (`ReactNode`): Shown before the label.
- `children` (`TreeNode[]`): Child nodes.
- `isBranch` (`boolean`): Treat the node as a branch before its children load.
- `disabled` (`boolean`): Skip the node when moving and selecting.

## Virtual List (@drift-ui/virtual-list)

Renders only the visible rows of a long list, with variable row heights and keyboard focus that survives scrolling.

Install: `npx shadcn@latest add @drift-ui/virtual-list`
Source: https://drift-ui.dev/r/virtual-list.json
Depends on: utils

Renders only the rows in view plus overscan (default 4 on each side). Give the list a fixed height through className, a row size guess through estimateSize, and a render function as children. Rows measure themselves, so heights can vary, and a row growing above the viewport does not shift what is on screen. Pass getItemKey for any list that can reorder or take inserts, so measured heights and focus follow the item rather than the index. The list has one tab stop. Arrow keys, PageUp, PageDown, Home and End move between rows, including rows not mounted yet, and the focused row stays mounted while scrolled away. Arrow keys typed inside a control in a row stay with that control. Pass aria-label to name the list.

```tsx
import { VirtualList } from "@/components/ui/virtual-list"

export function DeployLog({ lines }: { lines: { id: string; text: string }[] }) {
  return (
    <VirtualList
      aria-label="Deploy log"
      items={lines}
      estimateSize={32}
      getItemKey={(line) => line.id}
      className="h-96 rounded-lg border"
    >
      {(line) => <div className="px-3 py-1.5 font-mono text-xs">{line.text}</div>}
    </VirtualList>
  )
}
```

### VirtualList

`<T>`

A scrolling list that mounts only the rows in view. Rows measure themselves, so heights can vary, and the focused row stays mounted while scrolled away. Set a height through className.

- `items` (`T[]`, required): The full list of rows.
- `estimateSize` (`number`, required): Height in pixels assumed for a row until it is measured.
- `children` (`(item: T, index: number) => ReactNode`, required): Renders one row.
- `overscan` (`number`, default `4`): Extra rows mounted above and below the viewport.
- `getItemKey` (`(item: T, index: number) => Key`, default `index`): Stable identity for a row, so measured heights and focus follow it when the list changes.
Other props go to the <div>.

## Badge (@drift-ui/badge)

A small status label.

Install: `npx shadcn@latest add @drift-ui/badge`
Source: https://drift-ui.dev/r/badge.json
Depends on: utils, radix-ui, class-variance-authority

Identical API to the shadcn/ui component of the same name. Skip it if the project already has one.

## Button (@drift-ui/button)

A button with six variants and four sizes.

Install: `npx shadcn@latest add @drift-ui/button`
Source: https://drift-ui.dev/r/button.json
Depends on: utils, radix-ui, class-variance-authority

Identical API to the shadcn/ui component of the same name. Skip it if the project already has one.

## Card (@drift-ui/card)

A container with header, content, and footer slots.

Install: `npx shadcn@latest add @drift-ui/card`
Source: https://drift-ui.dev/r/card.json
Depends on: utils

Identical API to the shadcn/ui component of the same name. Skip it if the project already has one.

## Dialog (@drift-ui/dialog)

A modal window that traps focus and closes on Escape.

Install: `npx shadcn@latest add @drift-ui/dialog`
Source: https://drift-ui.dev/r/dialog.json
Depends on: utils, radix-ui, lucide-react

Identical API to the shadcn/ui component of the same name. Skip it if the project already has one.

## Input (@drift-ui/input)

A text input with focus and invalid states.

Install: `npx shadcn@latest add @drift-ui/input`
Source: https://drift-ui.dev/r/input.json
Depends on: utils

Identical API to the shadcn/ui component of the same name. Skip it if the project already has one.

## Label (@drift-ui/label)

An accessible label for form controls.

Install: `npx shadcn@latest add @drift-ui/label`
Source: https://drift-ui.dev/r/label.json
Depends on: utils, radix-ui

Identical API to the shadcn/ui component of the same name. Skip it if the project already has one.

## Popover (@drift-ui/popover)

Floating content anchored to a trigger.

Install: `npx shadcn@latest add @drift-ui/popover`
Source: https://drift-ui.dev/r/popover.json
Depends on: utils, radix-ui

Identical API to the shadcn/ui component of the same name. Skip it if the project already has one.

## Theme (@drift-ui/theme)

Neutral color tokens for light and dark mode, with AA contrast for secondary text.

Install: `npx shadcn@latest add @drift-ui/theme`
Source: https://drift-ui.dev/r/theme.json

Neutral oklch tokens for light and dark mode, written into the project's global CSS. Optional: components read whatever tokens the project already has.

## useControllableState (@drift-ui/use-controllable-state)

State that works controlled or uncontrolled, with a change callback.

Install: `npx shadcn@latest add @drift-ui/use-controllable-state`
Source: https://drift-ui.dev/r/use-controllable-state.json

Hook shared by several components to support both controlled (value + onValueChange) and uncontrolled (defaultValue) use. Installed automatically as a dependency.

## useCopyToClipboard (@drift-ui/use-copy-to-clipboard)

Copy text to the clipboard and remember what was copied for a moment.

Install: `npx shadcn@latest add @drift-ui/use-copy-to-clipboard`
Source: https://drift-ui.dev/r/use-copy-to-clipboard.json

Hook returning copy(text, key?) and copied, the key of the last copy (or null once 1.6 seconds pass). Installed automatically by description-list and json-viewer.

## Utils (@drift-ui/utils)

The cn() class merging helper.

Install: `npx shadcn@latest add @drift-ui/utils`
Source: https://drift-ui.dev/r/utils.json
Depends on: clsx, tailwind-merge

Installs lib/utils.ts with the cn() class merging helper. Every component depends on it.