# Prototyper UI — Full Documentation

> Composable React component library built on Base UI primitives. Tailwind CSS v4, OKLCH design tokens, shadcn-compatible.
> Tech stack: React 19, Next.js 15, Tailwind CSS v4, Base UI, TypeScript.
> Install components via: pnpm dlx shadcn@latest add https://prototyper-ui.com/r/{component}.json
<page url="https://prototyper-ui.com/docs/components/button" slug="components/button">
# Button
> A button with gradient variants built on Base UI
URL: https://prototyper-ui.com/docs/components/button
Base UI reference: https://base-ui.com/react/components/button
```tsx
import { Button } from "@/components/ui/button"

export default function ButtonDemo() {
  return <Button>Button</Button>
}
```

## Installation

```bash
pnpm dlx shadcn@latest add https://prototyper-ui.com/r/button.json
```

This will add the following files to your project:

- `components/ui/button.tsx`

## Usage

```tsx
import { Button } from "@/components/ui/button"

<Button>Click me</Button>
```

## Examples

### Destructive
```tsx
import { Button } from "@/components/ui/button"

export default function ButtonDestructive() {
  return <Button variant="destructive">Destructive</Button>
}
```

### Outline
```tsx
import { Button } from "@/components/ui/button"

export default function ButtonOutline() {
  return <Button variant="outline">Outline</Button>
}
```

### Secondary
```tsx
import { Button } from "@/components/ui/button"

export default function ButtonSecondary() {
  return <Button variant="secondary">Secondary</Button>
}
```

### Ghost
```tsx
import { Button } from "@/components/ui/button"

export default function ButtonGhost() {
  return <Button variant="ghost">Ghost</Button>
}
```

### Link
```tsx
import { buttonVariants } from "@/components/ui/button"

export default function ButtonLink() {
  return <a className={buttonVariants({ variant: "link" })}>Link</a>
}
```

### Icon
```tsx
import { ChevronRight } from "lucide-react"

import { Button } from "@/components/ui/button"

export default function ButtonIcon() {
  return (
    <Button variant="outline" size="icon" aria-label="Next">
      <ChevronRight className="size-4" />
    </Button>
  )
}
```

### With Icon
```tsx
import { Mail } from "lucide-react"

import { Button } from "@/components/ui/button"

export default function ButtonWithIcon() {
  return (
    <Button>
      <Mail className="mr-2 size-4" /> Login with Email
    </Button>
  )
}
```

### Loading
```tsx
import { Loader2 } from "lucide-react"

import { Button } from "@/components/ui/button"

export default function ButtonLoading() {
  return (
    <Button disabled>
      <Loader2 className="mr-2 size-4 animate-spin" />
      Please wait
    </Button>
  )
}
```

### Press
```tsx
import { Button } from "@/components/ui/button"

export default function ButtonPress() {
  return <Button onClick={() => alert("You pressed me")}>Button</Button>
}
```

## Styling

### Data Slots

Use `data-slot` attributes to target the button in CSS:

| Slot name | Element             |
| --------- | ------------------- |
| `button`  | The `<button>` root |

### Customization Examples

```css
/* Make all buttons pill-shaped */
[data-slot="button"] {
  @apply rounded-full;
}
```

```tsx
{/* Use className for one-off overrides */}
<Button className="rounded-full px-8">Pill Button</Button>
```

## API Reference

### Button

A clickable button element with gradient variants.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "destructive" \| "outline" \| "secondary" \| "ghost" \| "link"` | `"default"` | Visual style variant |
| `size` | `"default" \| "xs" \| "sm" \| "lg" \| "icon" \| "icon-xs" \| "icon-sm" \| "icon-lg"` | `"default"` | Size of the button |
| `isPending` | `boolean` | - | Shows pending state and sets aria-disabled |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Button content |

All [Base UI Button props](https://base-ui.com/react/components/button) are forwarded via `...props`.

### buttonVariants

A `cva` helper exported for use outside of the `<Button>` component (e.g., applying button styles to links).

```tsx
import { buttonVariants } from "@/components/ui/button"

<a className={buttonVariants({ variant: "outline" })}>Link styled as button</a>
```

## Accessibility

### Keyboard Interactions

| Key     | Action                                |
| ------- | ------------------------------------- |
| `Space` | Activates the button                  |
| `Enter` | Activates the button                  |
| `Tab`   | Moves focus to / away from the button |

### ARIA Attributes

- Renders as a native `<button>` element by default via Base UI.
- `aria-disabled="true"` is set when `isPending` is `true`.
- `data-pending` attribute is set during the pending state for styling.
</page>

<page url="https://prototyper-ui.com/docs/components/checkbox" slug="components/checkbox">
# Checkbox
> A checkbox with label and validation support built on Base UI
URL: https://prototyper-ui.com/docs/components/checkbox
Base UI reference: https://base-ui.com/react/components/checkbox
```tsx
import {
  Checkbox,
  CheckboxControl,
  CheckboxIndicator,
} from "@/components/ui/checkbox"

export default function CheckboxDemo() {
  return (
    <Checkbox>
      <CheckboxControl>
        <CheckboxIndicator />
      </CheckboxControl>
      Unsubscribe
    </Checkbox>
  )
}
```

## Installation

```bash
pnpm dlx shadcn@latest add https://prototyper-ui.com/r/checkbox.json
```

This will add the following files to your project:

- `components/ui/checkbox.tsx`

## Usage

```tsx
import { Checkbox, CheckboxControl, CheckboxIndicator } from "@/components/ui/checkbox"

<Checkbox>
  <CheckboxControl>
    <CheckboxIndicator />
  </CheckboxControl>
  Accept terms and conditions
</Checkbox>
```

## Anatomy

```tsx
<Checkbox>
  <CheckboxControl>
    <CheckboxIndicator />
  </CheckboxControl>
  {/* label text */}
</Checkbox>
```

| Sub-component       | `data-slot`          | Purpose                                      | Required |
| ------------------- | -------------------- | -------------------------------------------- | -------- |
| `Checkbox`          | `checkbox`           | Root provider, manages checked state         | Yes      |
| `CheckboxControl`   | `checkbox-control`   | Visual box that displays the check indicator | Yes      |
| `CheckboxIndicator` | `checkbox-indicator` | Checkmark or indeterminate icon              | Yes      |

## Examples

### Disabled
```tsx
import {
  Checkbox,
  CheckboxControl,
  CheckboxIndicator,
} from "@/components/ui/checkbox"

export default function CheckboxDisabled() {
  return (
    <Checkbox disabled>
      <CheckboxControl>
        <CheckboxIndicator />
      </CheckboxControl>
      Subscribe
    </Checkbox>
  )
}
```

### Indeterminate
```tsx
import {
  Checkbox,
  CheckboxControl,
  CheckboxIndicator,
} from "@/components/ui/checkbox"

export default function CheckboxIndeterminate() {
  return (
    <Checkbox indeterminate>
      <CheckboxControl>
        <CheckboxIndicator />
      </CheckboxControl>
      Subscribe
    </Checkbox>
  )
}
```

### Read Only
```tsx
import {
  Checkbox,
  CheckboxControl,
  CheckboxIndicator,
} from "@/components/ui/checkbox"

export default function CheckboxReadonly() {
  return (
    <Checkbox defaultChecked readOnly>
      <CheckboxControl>
        <CheckboxIndicator />
      </CheckboxControl>
      Agree
    </Checkbox>
  )
}
```

### Validation
```tsx
import {
  Checkbox,
  CheckboxControl,
  CheckboxIndicator,
} from "@/components/ui/checkbox"

export default function CheckboxValidation() {
  return (
    <Checkbox>
      <CheckboxControl>
        <CheckboxIndicator />
      </CheckboxControl>
      Subscribe
    </Checkbox>
  )
}
```

## Styling

### Data Slots

Use `data-slot` attributes to target specific parts of the checkbox:

| Slot name            | Element                                  |
| -------------------- | ---------------------------------------- |
| `checkbox`           | Root wrapper (label + control container) |
| `checkbox-control`   | The visual box element                   |
| `checkbox-indicator` | The checkmark / indeterminate icon       |

### Customization Examples

```css
/* Make all checkbox controls larger */
[data-slot="checkbox-control"] {
  @apply size-5 rounded-md;
}

/* Custom checked color */
[data-slot="checkbox-control"] {
  @apply group-data-checked:bg-green-600 group-data-checked:border-green-600;
}
```

```tsx
{/* Override styles via className */}
<Checkbox className="gap-4">
  <CheckboxControl className="size-5 rounded-md">
    <CheckboxIndicator />
  </CheckboxControl>
  Larger checkbox
</Checkbox>
```

## API Reference

### Checkbox

Root component that manages checked/unchecked/indeterminate state and renders as a label.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` | - | Controlled checked state |
| `defaultChecked` | `boolean` | `false` | Initial checked state for uncontrolled usage |
| `onCheckedChange` | `(checked: boolean, event: Event) => void` | - | Callback when checked state changes |
| `indeterminate` | `boolean` | `false` | Whether the checkbox is in an indeterminate state |
| `disabled` | `boolean` | `false` | Whether the checkbox is disabled |
| `readOnly` | `boolean` | `false` | Whether the checkbox is read-only |
| `required` | `boolean` | `false` | Whether the checkbox is required |
| `name` | `string` | - | Name attribute for form submission |
| `value` | `string` | - | Value attribute for form submission |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Checkbox label and control content |

All [Base UI Checkbox.Root props](https://base-ui.com/react/components/checkbox) are forwarded via `...props`.

### CheckboxControl

The visual box element that displays the check indicator.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Custom content (typically CheckboxIndicator) |

All standard `span` props are forwarded via `...props`.

### CheckboxIndicator

The checkmark or indeterminate icon rendered inside the control.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Custom indicator icon (defaults to SVG checkmark) |

All [Base UI Checkbox.Indicator props](https://base-ui.com/react/components/checkbox) are forwarded via `...props`.

## Accessibility

### Keyboard Interactions

| Key     | Action                                |
| ------- | ------------------------------------- |
| `Space` | Toggles the checkbox checked state    |
| `Tab`   | Moves focus to / away from the checkbox |

### ARIA Attributes

- Renders with `role="checkbox"` via Base UI.
- `aria-checked` is set to `true`, `false`, or `mixed` (indeterminate) based on state.
- `aria-disabled` is set when the checkbox is disabled.
- `aria-readonly` is set when the checkbox is read-only.
- `aria-required` is set when the checkbox is required.
- Screen readers announce the checkbox label and its checked/unchecked/mixed state.
</page>

<page url="https://prototyper-ui.com/docs/components/combobox" slug="components/combobox">
# Combobox
> An autocomplete input with filtering and selection built on Base UI
URL: https://prototyper-ui.com/docs/components/combobox
Base UI reference: https://base-ui.com/react/components/combobox
```tsx
"use client"

import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@/components/ui/combobox"

const frameworks = ["Next.js", "SvelteKit", "Nuxt.js", "Remix", "Astro"]

export default function ComboboxDemo() {
  return (
    <Combobox items={frameworks}>
      <ComboboxInput placeholder="Select a framework" />
      <ComboboxContent>
        <ComboboxEmpty>No results found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}
```

## Installation

```bash
pnpm dlx shadcn@latest add https://prototyper-ui.com/r/combobox.json
```

This will add the following files to your project:

- `components/ui/combobox.tsx`

## Usage

```tsx
import {
  Combobox,
  ComboboxInput,
  ComboboxContent,
  ComboboxList,
  ComboboxItem,
  ComboboxEmpty,
} from "@/components/ui/combobox"

<Combobox items={items}>
  <ComboboxInput placeholder="Search..." />
  <ComboboxContent>
    <ComboboxEmpty>No results found.</ComboboxEmpty>
    <ComboboxList>
      {(item) => (
        <ComboboxItem key={item} value={item}>
          {item}
        </ComboboxItem>
      )}
    </ComboboxList>
  </ComboboxContent>
</Combobox>
```

## Anatomy

```tsx
<Combobox>
  <ComboboxInput />
  <ComboboxContent>
    <ComboboxEmpty />
    <ComboboxGroup>
      <ComboboxGroupLabel />
      <ComboboxList>
        <ComboboxItem />
      </ComboboxList>
    </ComboboxGroup>
  </ComboboxContent>
</Combobox>
```

Or with chips for multi-select:

```tsx
<Combobox>
  <ComboboxChips>
    <ComboboxChip>
      <ComboboxChipRemove />
    </ComboboxChip>
    <ComboboxChipsInput />
  </ComboboxChips>
  <ComboboxContent>
    <ComboboxList>
      <ComboboxItem />
    </ComboboxList>
  </ComboboxContent>
</Combobox>
```

| Sub-component         | `data-slot`              | Purpose                                              | Required |
| --------------------- | ------------------------ | ---------------------------------------------------- | -------- |
| `Combobox`            | -                        | Root provider, manages state and filtering           | Yes      |
| `ComboboxInput`       | `input-group-control`    | Text input with optional trigger and clear buttons   | Yes*     |
| `ComboboxChipsInput`  | `combobox-chips-input`   | Text input for use inside `ComboboxChips`            | Yes*     |
| `ComboboxTrigger`     | `combobox-trigger`       | Button that toggles the popup open/closed            | No       |
| `ComboboxClear`       | `combobox-clear`         | Button that clears the current selection             | No       |
| `ComboboxValue`       | `combobox-value`         | Displays the selected value                          | No       |
| `ComboboxContent`     | `combobox-content`       | Positioned popup containing the list                 | Yes      |
| `ComboboxList`        | `combobox-list`          | Scrollable list of items                             | Yes      |
| `ComboboxItem`        | `combobox-item`          | Individual selectable option                         | Yes      |
| `ComboboxEmpty`       | `combobox-empty`         | Shown when no items match the filter                 | No       |
| `ComboboxGroup`       | `combobox-group`         | Groups related items together                        | No       |
| `ComboboxGroupLabel`  | `combobox-group-label`   | Label for a group of items                           | No       |
| `ComboboxSeparator`   | `combobox-separator`     | Visual separator between groups                      | No       |
| `ComboboxIcon`        | `combobox-icon`          | Icon element inside the combobox                     | No       |
| `ComboboxChips`       | `combobox-chips`         | Container for selected chips in multi-select mode    | No       |
| `ComboboxChip`        | `combobox-chip`          | Individual chip representing a selected value        | No       |
| `ComboboxChipRemove`  | `combobox-chip-remove`   | Button to remove a chip                              | No       |
| `ComboboxStatus`      | `combobox-status`        | Screen-reader-only status message                    | No       |
| `ComboboxArrow`       | `combobox-arrow`         | Arrow pointing from popup to trigger                 | No       |
| `ComboboxBackdrop`    | `combobox-backdrop`      | Full-screen backdrop behind the popup                | No       |

\* Use either `ComboboxInput` or `ComboboxChipsInput`, not both.

## Examples

### Content
```tsx
"use client"

import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@/components/ui/combobox"

type Framework = { label: string; value: string }

const frameworks: Framework[] = [
  { label: "Next.js", value: "nextjs" },
  { label: "SvelteKit", value: "sveltekit" },
  { label: "Nuxt.js", value: "nuxtjs" },
  { label: "Remix", value: "remix" },
  { label: "Astro", value: "astro" },
  { label: "Gatsby", value: "gatsby" },
]

export default function ComboboxContentExample() {
  return (
    <Combobox items={frameworks} itemToStringLabel={(f) => f.label}>
      <ComboboxInput placeholder="Select a framework" />
      <ComboboxContent>
        <ComboboxEmpty>No results found.</ComboboxEmpty>
        <ComboboxList>
          {(framework: Framework) => (
            <ComboboxItem key={framework.value} value={framework}>
              {framework.label}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}
```

### Description
```tsx
"use client"

import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@/components/ui/combobox"

const frameworks = ["Next.js", "SvelteKit", "Nuxt.js", "Remix", "Astro"]

export default function ComboboxDescription() {
  return (
    <Combobox items={frameworks} name="framework">
      <label className="text-sm font-medium">Framework</label>
      <ComboboxInput placeholder="Select a framework" />
      <p className="text-sm text-muted-foreground">
        Choose the framework you use for your projects.
      </p>
      <ComboboxContent>
        <ComboboxEmpty>No results found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}
```

### Disabled
```tsx
"use client"

import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@/components/ui/combobox"

const frameworks = ["Next.js", "SvelteKit", "Nuxt.js", "Remix", "Astro"]

export default function ComboboxDisabled() {
  return (
    <Combobox items={frameworks} disabled>
      <ComboboxInput placeholder="Select a framework" />
      <ComboboxContent>
        <ComboboxEmpty>No results found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}
```

### Disabled Items
```tsx
"use client"

import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@/components/ui/combobox"

const fruits = [
  "Apple",
  "Banana",
  "Blueberry",
  "Grape",
  "Pineapple",
]

const disabledItems = ["Banana", "Grape"]

export default function ComboboxDisabledItems() {
  return (
    <Combobox items={fruits}>
      <ComboboxInput placeholder="Select a fruit" />
      <ComboboxContent>
        <ComboboxEmpty>No results found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem
              key={item}
              value={item}
              disabled={disabledItems.includes(item)}
            >
              {disabledItems.includes(item)
                ? `${item} (out of stock)`
                : item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}
```

### Filtering
```tsx
"use client"

import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@/components/ui/combobox"

const languages = [
  "Bash",
  "C",
  "C++",
  "C#",
  "Dart",
  "Elixir",
  "Erlang",
  "Go",
  "Haskell",
  "Java",
  "JavaScript",
  "Kotlin",
  "Lua",
  "Objective-C",
  "PHP",
  "Python",
  "R",
  "Ruby",
  "Rust",
  "Scala",
  "SQL",
  "Swift",
  "TypeScript",
  "Zig",
]

export default function ComboboxFiltering() {
  return (
    <Combobox items={languages}>
      <ComboboxInput placeholder="Search a language..." />
      <ComboboxContent>
        <ComboboxEmpty>No languages found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}
```

### Links
```tsx
"use client"

import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@/components/ui/combobox"

type Company = { label: string; value: string; url: string }

const companies: Company[] = [
  { label: "Adobe", value: "adobe", url: "https://adobe.com/" },
  { label: "Apple", value: "apple", url: "https://apple.com/" },
  { label: "Google", value: "google", url: "https://google.com/" },
  { label: "Microsoft", value: "microsoft", url: "https://microsoft.com/" },
  { label: "Netflix", value: "netflix", url: "https://netflix.com/" },
]

export default function ComboboxLinks() {
  return (
    <Combobox items={companies} itemToStringLabel={(c) => c.label}>
      <ComboboxInput placeholder="Visit a company website" />
      <ComboboxContent>
        <ComboboxEmpty>No results found.</ComboboxEmpty>
        <ComboboxList>
          {(company: Company) => (
            <ComboboxItem
              key={company.value}
              value={company}
              render={
                <a
                  href={company.url}
                  target="_blank"
                  rel="noopener noreferrer"
                />
              }
            >
              {company.label}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}
```

### Multiple
```tsx
"use client"

import * as React from "react"
import {
  Combobox,
  ComboboxChip,
  ComboboxChipRemove,
  ComboboxChips,
  ComboboxChipsInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxItem,
  ComboboxList,
  ComboboxValue,
} from "@/components/ui/combobox"

const frameworks = [
  "Next.js",
  "SvelteKit",
  "Nuxt.js",
  "Remix",
  "Astro",
  "Gatsby",
  "Solid Start",
]

export default function ComboboxMultiple() {
  const [value, setValue] = React.useState<string[]>([])

  return (
    <Combobox
      items={frameworks}
      multiple
      value={value}
      onValueChange={setValue}
    >
      <ComboboxChips>
        <ComboboxValue>
          {value.map((item) => (
            <ComboboxChip key={item}>
              {item}
              <ComboboxChipRemove />
            </ComboboxChip>
          ))}
        </ComboboxValue>
        <ComboboxChipsInput placeholder="Add a framework" />
      </ComboboxChips>
      <ComboboxContent>
        <ComboboxEmpty>No results found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}
```

### Sections
```tsx
"use client"

import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxGroup,
  ComboboxInput,
  ComboboxItem,
  ComboboxLabel,
  ComboboxList,
} from "@/components/ui/combobox"

const items = [
  {
    value: "fruits",
    items: ["Apple", "Banana", "Orange", "Pear", "Grape", "Strawberry"],
  },
  {
    value: "vegetables",
    items: ["Carrot", "Broccoli", "Spinach", "Potato", "Lettuce", "Tomato"],
  },
]

export default function ComboboxSections() {
  return (
    <Combobox items={items}>
      <ComboboxInput placeholder="Select a fruit or vegetable" />
      <ComboboxContent>
        <ComboboxEmpty>No results found.</ComboboxEmpty>
        <ComboboxList>
          {(group) => (
            <ComboboxGroup key={group.value}>
              <ComboboxLabel>
                {group.value === "fruits" ? "Fruits" : "Vegetables"}
              </ComboboxLabel>
              {group.items.map((item: string) => (
                <ComboboxItem key={item} value={item}>
                  {item}
                </ComboboxItem>
              ))}
            </ComboboxGroup>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}
```

### Text Slots
```tsx
"use client"

import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@/components/ui/combobox"

type Action = { label: string; value: string; description: string }

const actions: Action[] = [
  {
    label: "Add to queue",
    value: "add-to-queue",
    description: "Add to current watch queue.",
  },
  {
    label: "Add review",
    value: "add-review",
    description: "Post a review for the episode.",
  },
  {
    label: "Subscribe",
    value: "subscribe",
    description: "Get notified about new episodes.",
  },
  {
    label: "Report",
    value: "report",
    description: "Report an issue or violation.",
  },
]

export default function ComboboxTextSlots() {
  return (
    <Combobox items={actions} itemToStringLabel={(a) => a.label}>
      <ComboboxInput placeholder="Select an action" />
      <ComboboxContent>
        <ComboboxEmpty>No results found.</ComboboxEmpty>
        <ComboboxList>
          {(action: Action) => (
            <ComboboxItem
              key={action.value}
              value={action}
              className="flex flex-col items-start"
            >
              <span>{action.label}</span>
              <span className="text-sm text-muted-foreground">
                {action.description}
              </span>
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}
```

### Validation
```tsx
"use client"

import { Button } from "@/components/ui/button"
import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@/components/ui/combobox"
import { FieldError } from "@/components/ui/field"

const frameworks = ["Next.js", "SvelteKit", "Nuxt.js", "Remix", "Astro"]

export default function ComboboxValidation() {
  return (
    <form className="flex flex-col gap-2">
      <Combobox items={frameworks} name="framework" required>
        <label className="text-sm font-medium">Framework</label>
        <ComboboxInput placeholder="Select a framework" />
        <FieldError />
        <ComboboxContent>
          <ComboboxEmpty>No results found.</ComboboxEmpty>
          <ComboboxList>
            {(item) => (
              <ComboboxItem key={item} value={item}>
                {item}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
      <Button className="w-fit" type="submit">
        Submit
      </Button>
    </form>
  )
}
```

## Styling

### Data Slots

Use `data-slot` attributes to target specific parts of the combobox:

| Slot name              | Element                                    |
| ---------------------- | ------------------------------------------ |
| `input-group-control`  | The text input element                     |
| `combobox-trigger`     | Dropdown trigger button                    |
| `combobox-clear`       | Clear selection button                     |
| `combobox-content`     | Positioned popup panel                     |
| `combobox-list`        | Scrollable list container                  |
| `combobox-item`        | Individual option                          |
| `combobox-empty`       | Empty state message                        |
| `combobox-group`       | Group container                            |
| `combobox-group-label` | Group label                                |
| `combobox-separator`   | Separator line between groups              |
| `combobox-chips`       | Chips container for multi-select           |
| `combobox-chip`        | Individual chip                            |
| `combobox-chip-remove` | Chip remove button                         |
| `combobox-chips-input` | Input within chips container               |
| `combobox-value`       | Selected value display                     |
| `combobox-icon`        | Icon element                               |
| `combobox-status`      | Screen-reader status (visually hidden)     |
| `combobox-arrow`       | Popup arrow                                |
| `combobox-backdrop`    | Full-screen backdrop                       |

### Customization Examples

```css
/* Widen the popup */
[data-slot="combobox-content"] {
  @apply min-w-[20rem];
}

/* Custom highlighted item style */
[data-slot="combobox-item"][data-highlighted] {
  @apply bg-primary text-primary-foreground;
}
```

```tsx
{/* Override popup alignment */}
<ComboboxContent align="center" sideOffset={8}>
  {/* ... */}
</ComboboxContent>
```

## API Reference

### Combobox

Root component that manages filtering, selection, and open/close state.

All [Base UI Combobox.Root props](https://base-ui.com/react/components/combobox) are forwarded via `...props`.

### ComboboxInput

Text input with optional trigger and clear buttons, wrapped in an `InputGroup`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `showTrigger` | `boolean` | `true` | Show the dropdown trigger button |
| `showClear` | `boolean` | `false` | Show the clear selection button |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Additional content after the input |

All [Base UI Combobox.Input props](https://base-ui.com/react/components/combobox) are forwarded via `...props`.

### ComboboxChipsInput

Minimal text input for use within the `ComboboxChips` container.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Combobox.Input props](https://base-ui.com/react/components/combobox) are forwarded via `...props`.

### ComboboxTrigger

Button that toggles the popup open or closed. Renders a chevron-down icon by default.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Custom icon (replaces default chevron) |

All [Base UI Combobox.Trigger props](https://base-ui.com/react/components/combobox) are forwarded via `...props`.

### ComboboxClear

Button that clears the current selection. Renders an X icon by default.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Custom icon (replaces default X) |

All [Base UI Combobox.Clear props](https://base-ui.com/react/components/combobox) are forwarded via `...props`.

### ComboboxValue

Displays the selected value text.

All [Base UI Combobox.Value props](https://base-ui.com/react/components/combobox) are forwarded via `...props`.

### ComboboxContent

Positioned popup that contains the list. Wraps `Combobox.Portal`, `Combobox.Positioner`, and `Combobox.Popup`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | Side of the anchor to position on |
| `sideOffset` | `number` | `4` | Distance from the anchor |
| `align` | `"start" \| "center" \| "end"` | `"start"` | Alignment along the side axis |
| `alignOffset` | `number` | `0` | Offset along the alignment axis |
| `anchor` | `ComboboxPrimitive.Positioner.Props["anchor"]` | - | Custom anchor element |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Combobox.Popup props](https://base-ui.com/react/components/combobox) are forwarded via `...props`.

### ComboboxList

Scrollable list container for combobox items.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Combobox.List props](https://base-ui.com/react/components/combobox) are forwarded via `...props`.

### ComboboxItem

Individual selectable option. Includes a check icon indicator when selected.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Item content |

All [Base UI Combobox.Item props](https://base-ui.com/react/components/combobox) are forwarded via `...props`.

### ComboboxEmpty

Message shown when no items match the current filter.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Combobox.Empty props](https://base-ui.com/react/components/combobox) are forwarded via `...props`.

### ComboboxGroup

Groups related combobox items together.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Combobox.Group props](https://base-ui.com/react/components/combobox) are forwarded via `...props`.

### ComboboxGroupLabel

Label for a group of items.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Combobox.GroupLabel props](https://base-ui.com/react/components/combobox) are forwarded via `...props`.

### ComboboxSeparator

Visual separator between groups.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Combobox.Separator props](https://base-ui.com/react/components/combobox) are forwarded via `...props`.

### ComboboxIcon

Icon element within the combobox.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Combobox.Icon props](https://base-ui.com/react/components/combobox) are forwarded via `...props`.

### ComboboxChips

Container for selected value chips in multi-select mode.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Combobox.Chips props](https://base-ui.com/react/components/combobox) are forwarded via `...props`.

### ComboboxChip

Individual chip representing a selected value.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Combobox.Chip props](https://base-ui.com/react/components/combobox) are forwarded via `...props`.

### ComboboxChipRemove

Button to remove a chip. Renders an X icon by default.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Custom icon (replaces default X) |

All [Base UI Combobox.ChipRemove props](https://base-ui.com/react/components/combobox) are forwarded via `...props`.

### ComboboxStatus

Screen-reader-only status message that announces changes.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Combobox.Status props](https://base-ui.com/react/components/combobox) are forwarded via `...props`.

### ComboboxArrow

Arrow element pointing from the popup to the trigger.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Combobox.Arrow props](https://base-ui.com/react/components/combobox) are forwarded via `...props`.

### ComboboxBackdrop

Full-screen backdrop rendered behind the popup.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Combobox.Backdrop props](https://base-ui.com/react/components/combobox) are forwarded via `...props`.

### ComboboxCollection

Re-export of `ComboboxPrimitive.Collection` for defining static item collections.

### useComboboxFilter

Re-export of `ComboboxPrimitive.useFilter` hook for custom filtering logic.

### useComboboxAnchor

Utility hook that returns a ref for anchoring the combobox popup to a custom element.

```tsx
import { useComboboxAnchor } from "@/components/ui/combobox"

const anchorRef = useComboboxAnchor()
```

## Accessibility

### Keyboard Interactions

| Key          | Action                                                          |
| ------------ | --------------------------------------------------------------- |
| `ArrowDown`  | Opens the popup (if closed) or moves to the next item           |
| `ArrowUp`    | Opens the popup (if closed) or moves to the previous item       |
| `Enter`      | Selects the highlighted item and closes the popup               |
| `Escape`     | Closes the popup                                                |
| `Home`       | Moves to the first item in the list                             |
| `End`        | Moves to the last item in the list                              |
| `Tab`        | Closes the popup and moves focus to the next element            |
| `Backspace`  | Removes the last chip (in multi-select chips mode)              |

### ARIA Attributes

- The input has `role="combobox"` with `aria-expanded` indicating popup state.
- `aria-activedescendant` tracks the currently highlighted item.
- `aria-autocomplete` indicates the filtering behavior.
- `ComboboxContent` has `role="listbox"` for the list of options.
- `ComboboxItem` has `role="option"` with `aria-selected` for selected state and `aria-disabled` for disabled items.
- `ComboboxGroup` uses `role="group"` with `aria-labelledby` linked to the group label.
- `ComboboxStatus` provides a live region for screen reader announcements.
- `ComboboxClear` has `aria-label="Clear selection"` for screen reader users.
</page>

<page url="https://prototyper-ui.com/docs/components/dialog" slug="components/dialog">
# Dialog
> A modal dialog with sheet variant built on Base UI
URL: https://prototyper-ui.com/docs/components/dialog
Base UI reference: https://base-ui.com/react/components/dialog
```tsx
import { Button } from "@/components/ui/button"
import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog"
import { FieldLabel } from "@/components/ui/field"
import { TextField, Input } from "@/components/ui/textfield"

export default function DialogDemo() {
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="outline" />}>
        Sign up...
      </DialogTrigger>
      <DialogContent className="sm:max-w-[425px]">
        <DialogHeader>
          <DialogTitle>Sign up</DialogTitle>
        </DialogHeader>
        <div className="grid gap-4 py-4">
          <TextField autoFocus>
            <FieldLabel>First Name</FieldLabel>
            <Input />
          </TextField>
          <TextField>
            <FieldLabel>Last Name</FieldLabel>
            <Input />
          </TextField>
        </div>
        <DialogFooter>
          <DialogClose render={<Button type="submit" />}>
            Save changes
          </DialogClose>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}
```

## Installation

```bash
pnpm dlx shadcn@latest add https://prototyper-ui.com/r/dialog.json
```

This will add the following files to your project:

- `components/ui/dialog.tsx`

## Usage

```tsx
import {
  Dialog,
  DialogTrigger,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogDescription,
} from "@/components/ui/dialog"

<Dialog>
  <DialogTrigger>Open</DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Dialog Title</DialogTitle>
      <DialogDescription>Dialog description.</DialogDescription>
    </DialogHeader>
  </DialogContent>
</Dialog>
```

## Anatomy

```tsx
<Dialog>
  <DialogTrigger />
  <DialogContent>
    <DialogHeader>
      <DialogTitle />
      <DialogDescription />
    </DialogHeader>
    {/* your content */}
    <DialogFooter>
      <DialogClose />
    </DialogFooter>
  </DialogContent>
</Dialog>
```

| Sub-component      | `data-slot`          | Purpose                                           | Required |
| ------------------ | -------------------- | ------------------------------------------------- | -------- |
| `Dialog`           | `dialog`             | Root provider, manages open/close state            | Yes      |
| `DialogTrigger`    | `dialog-trigger`     | Button that opens the dialog                       | Yes      |
| `DialogPortal`     | `dialog-portal`      | Renders children into a portal                     | No       |
| `DialogOverlay`    | `dialog-overlay`     | Backdrop behind the dialog                         | No       |
| `DialogContent`    | `dialog-content`     | The dialog popup panel                             | Yes      |
| `DialogHeader`     | `dialog-header`      | Flex container for title and description           | No       |
| `DialogTitle`      | `dialog-title`       | Accessible title for the dialog                    | Yes      |
| `DialogDescription`| `dialog-description` | Accessible description for the dialog              | No       |
| `DialogFooter`     | `dialog-footer`      | Flex container for action buttons                  | No       |
| `DialogClose`      | `dialog-close`       | Button that closes the dialog                      | No       |

## Examples

### Alert Dialog
```tsx
import { Button } from "@/components/ui/button"
import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog"

export default function AlertDialogDemo() {
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="outline" />}>
        Delete...
      </DialogTrigger>
      <DialogContent showCloseButton={false} className="sm:max-w-[425px]">
        <DialogHeader>
          <DialogTitle>Delete file</DialogTitle>
          <DialogDescription>
            This will permanently delete the selected file. Continue?
          </DialogDescription>
        </DialogHeader>
        <DialogFooter>
          <DialogClose render={<Button />}>
            Cancel
          </DialogClose>
          <DialogClose render={<Button variant="destructive" />}>
            Delete
          </DialogClose>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}
```

### Sheet
```tsx
import { Button } from "@/components/ui/button"
import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog"
import { FieldLabel } from "@/components/ui/field"
import { Switch } from "@/components/ui/switch"
import { TextField, Input } from "@/components/ui/textfield"

export default function DialogSheet() {
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="outline" />}>
        Open Settings
      </DialogTrigger>
      <DialogContent side="right">
        <DialogHeader>
          <DialogTitle>Settings</DialogTitle>
          <DialogDescription>
            Manage your account preferences and notification settings.
          </DialogDescription>
        </DialogHeader>
        <div className="flex flex-col gap-6 py-2">
          <div className="flex flex-col gap-4">
            <p className="text-sm font-medium">Profile</p>
            <TextField>
              <FieldLabel>Display Name</FieldLabel>
              <Input placeholder="Your name" />
            </TextField>
            <TextField>
              <FieldLabel>Email</FieldLabel>
              <Input type="email" placeholder="you@example.com" />
            </TextField>
          </div>
          <div className="flex flex-col gap-3">
            <p className="text-sm font-medium">Notifications</p>
            <div className="flex items-center justify-between">
              <span className="text-sm">Email notifications</span>
              <Switch defaultChecked />
            </div>
            <div className="flex items-center justify-between">
              <span className="text-sm">Marketing emails</span>
              <Switch />
            </div>
          </div>
        </div>
        <DialogFooter showCloseButton>
          <DialogClose render={<Button />}>Save changes</DialogClose>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}
```

## Styling

### Data Slots

Use `data-slot` attributes to target specific parts of the dialog:

| Slot name            | Element                                  |
| -------------------- | ---------------------------------------- |
| `dialog`             | Root provider (no DOM element rendered)  |
| `dialog-trigger`     | The trigger button                       |
| `dialog-portal`      | Portal wrapper                           |
| `dialog-overlay`     | Backdrop overlay                         |
| `dialog-content`     | The popup panel                          |
| `dialog-header`      | Header container (title + description)   |
| `dialog-title`       | Title heading                            |
| `dialog-description` | Description paragraph                    |
| `dialog-footer`      | Footer container (action buttons)        |
| `dialog-close`       | Close button(s)                          |

### Customization Examples

```css
/* Make dialogs wider by default */
[data-slot="dialog-content"] {
  @apply sm:max-w-lg;
}

/* Custom overlay color */
[data-slot="dialog-overlay"] {
  @apply bg-black/30;
}
```

```tsx
{/* Override width via className */}
<DialogContent className="sm:max-w-2xl">
  {/* ... */}
</DialogContent>
```

## API Reference

### Dialog

Root component that manages open/close state.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | - | Controlled open state |
| `onOpenChange` | `(open: boolean) => void` | - | Callback when open state changes |
| `defaultOpen` | `boolean` | `false` | Initial open state for uncontrolled usage |
| `modal` | `boolean` | `true` | Whether the dialog is modal |

All [Base UI Dialog.Root props](https://base-ui.com/react/components/dialog) are forwarded via `...props`.

### DialogTrigger

Button that opens the dialog when clicked.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Dialog.Trigger props](https://base-ui.com/react/components/dialog) are forwarded via `...props`.

### DialogContent

The popup panel rendered inside a portal with an overlay backdrop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `showCloseButton` | `boolean` | `true` | Whether to show the X close button |
| `side` | `"top" \| "bottom" \| "left" \| "right"` | - | Turns the dialog into a sheet from this side |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Dialog content |

All [Base UI Dialog.Popup props](https://base-ui.com/react/components/dialog) are forwarded via `...props`.

### DialogHeader

Flex column container for title and description.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Header content |

All standard `div` props are forwarded via `...props`.

### DialogFooter

Flex row container for action buttons.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `showCloseButton` | `boolean` | `false` | Whether to render a "Close" button |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Footer content |

All standard `div` props are forwarded via `...props`.

### DialogTitle

Accessible title for the dialog, rendered as a heading.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Dialog.Title props](https://base-ui.com/react/components/dialog) are forwarded via `...props`.

### DialogDescription

Accessible description rendered below the title.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Dialog.Description props](https://base-ui.com/react/components/dialog) are forwarded via `...props`.

### DialogClose

Button that closes the dialog when clicked.

All [Base UI Dialog.Close props](https://base-ui.com/react/components/dialog) are forwarded via `...props`.

### DialogOverlay

Backdrop overlay behind the dialog.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Dialog.Backdrop props](https://base-ui.com/react/components/dialog) are forwarded via `...props`.

### DialogPortal

Renders children into a React portal.

All [Base UI Dialog.Portal props](https://base-ui.com/react/components/dialog) are forwarded via `...props`.

## Accessibility

### Keyboard Interactions

| Key         | Action                                                           |
| ----------- | ---------------------------------------------------------------- |
| `Escape`    | Closes the dialog                                                |
| `Tab`       | Moves focus to the next focusable element within the dialog      |
| `Shift+Tab` | Moves focus to the previous focusable element within the dialog  |

### ARIA Attributes

- `DialogContent` receives `role="dialog"` (or `role="alertdialog"` when used as an alert dialog).
- `aria-modal="true"` is set when the dialog is modal.
- `aria-labelledby` is automatically linked to `DialogTitle`.
- `aria-describedby` is automatically linked to `DialogDescription`.
- Focus is trapped inside the dialog while it is open.
- Focus returns to the trigger element when the dialog closes.
</page>

<page url="https://prototyper-ui.com/docs/components/field" slug="components/field">
# Field
> Form field wrapper with label, description, and error message
URL: https://prototyper-ui.com/docs/components/field
Base UI reference: https://base-ui.com/react/components/field
## Installation

```bash
pnpm dlx shadcn@latest add https://prototyper-ui.com/r/field.json
```

This will add the following files to your project:

- `components/ui/field.tsx`

## Usage

```tsx
import { Field, FieldLabel, FieldDescription } from "@/components/ui/field"

<Field>
  <FieldLabel>Email</FieldLabel>
  <input />
  <FieldDescription>Enter your email address.</FieldDescription>
</Field>
```

## Anatomy

```tsx
<FieldSet>
  <FieldLegend />
  <Field>
    <FieldLabel>
      {/* input, checkbox, or other control */}
    </FieldLabel>
    <FieldContent>
      <FieldDescription />
      <FieldError />
    </FieldContent>
  </Field>
  <FieldSeparator />
</FieldSet>
```

Or with `FieldGroup` for grouped inputs:

```tsx
<Field>
  <FieldLabel />
  <FieldGroup>
    {/* grouped inputs or controls */}
  </FieldGroup>
  <FieldDescription />
  <FieldError />
</Field>
```

| Sub-component      | `data-slot`          | Purpose                                                 | Required |
| ------------------ | -------------------- | ------------------------------------------------------- | -------- |
| `Field`            | `field`              | Root wrapper, provides layout and orientation            | Yes      |
| `FieldLabel`       | `field-label`        | Label for the field control                              | No       |
| `FieldTitle`       | `field-label`        | Non-interactive label text (renders as `div`)            | No       |
| `FieldDescription` | `field-description`  | Helper/description text                                  | No       |
| `FieldError`       | `field-error`        | Validation error message with `role="alert"`             | No       |
| `FieldGroup`       | `field-group`        | Styled group container for composed inputs               | No       |
| `FieldContent`     | `field-content`      | Content wrapper for description and error                | No       |
| `FieldSet`         | `field-set`          | Fieldset element for grouping multiple fields            | No       |
| `FieldLegend`      | `field-legend`       | Legend for a fieldset                                    | No       |
| `FieldSeparator`   | `field-separator`    | Visual separator between fields                          | No       |

## Examples

This component does not have standalone examples. It is used as a building block within [TextField](/docs/components/textfield), [NumberField](/docs/components/numberfield), [Checkbox](/docs/components/checkbox), [Radio Group](/docs/components/radio-group), and other form components.

## Styling

### Data Slots

Use `data-slot` attributes to target specific parts of the field:

| Slot name            | Element                                    |
| -------------------- | ------------------------------------------ |
| `field`              | Root wrapper div                           |
| `field-label`        | Label element                              |
| `field-description`  | Description paragraph                      |
| `field-error`        | Error message container                    |
| `field-group`        | Grouped input container                    |
| `field-content`      | Content wrapper (description + error)      |
| `field-set`          | Fieldset element                           |
| `field-legend`       | Legend element                             |
| `field-separator`    | Visual separator                           |

### Customization Examples

```css
/* Change label styling globally */
[data-slot="field-label"] {
  @apply text-base font-semibold;
}

/* Style error messages */
[data-slot="field-error"] {
  @apply text-xs font-medium;
}
```

```tsx
{/* Override field orientation */}
<Field orientation="horizontal">
  <FieldLabel>Name</FieldLabel>
  <input />
</Field>
```

## API Reference

### Field

Root wrapper that provides layout direction and grouping for form controls.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"vertical" \| "horizontal" \| "responsive"` | `"vertical"` | Layout direction of the field |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Field content |

All standard `div` props are forwarded via `...props`.

### FieldLabel

Label element that wraps or precedes a form control. Built on the `Label` component.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Label content |

All Label props are forwarded via `...props`.

### FieldTitle

Non-interactive label text rendered as a `div` instead of a `<label>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Title content |

All standard `div` props are forwarded via `...props`.

### FieldDescription

Descriptive helper text rendered below the control.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Description content |

All standard `p` props are forwarded via `...props`.

### FieldError

Validation error message with live-region semantics.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `errors` | `Array<{ message?: string } \| undefined>` | - | Array of error objects to display |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Custom error content (overrides errors prop) |

All standard `div` props are forwarded via `...props`.

### FieldGroup

Styled container for grouping multiple inputs or controls.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "ghost"` | `"default"` | Visual style of the group container |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Grouped content |

All standard `div` props are forwarded via `...props`.

### FieldContent

Flex column wrapper for description and error message content.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Content |

All standard `div` props are forwarded via `...props`.

### FieldSet

A `<fieldset>` element for grouping related fields.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Fieldset content |

All standard `fieldset` props are forwarded via `...props`.

### FieldLegend

Legend element for a fieldset.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"legend" \| "label"` | `"legend"` | Text size variant |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Legend content |

All standard `legend` props are forwarded via `...props`.

### FieldSeparator

Visual separator between fields, optionally with content.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Optional content displayed on separator |

All standard `div` props are forwarded via `...props`.

## Accessibility

### Keyboard Interactions

| Key   | Action                                    |
| ----- | ----------------------------------------- |
| `Tab` | Moves focus to the next focusable control |

### ARIA Attributes

- `Field` renders with `role="group"` to semantically group the label, control, and messages.
- `FieldError` renders with `role="alert"` and `aria-live="polite"` so error messages are announced by screen readers when they appear.
- `data-orientation` is set on the field root to indicate layout direction.
- `data-invalid` can be set to indicate validation errors.
- `data-disabled` is set when the field is disabled, and disabled styling propagates to child labels.
</page>

<page url="https://prototyper-ui.com/docs/components/menu" slug="components/menu">
# Menu
> A dropdown menu with submenus and selection built on Base UI
URL: https://prototyper-ui.com/docs/components/menu
Base UI reference: https://base-ui.com/react/components/menu
```tsx
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "@/components/ui/menu"

import { Button } from "@/components/ui/button"

export default function MenuDemo() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button aria-label="Menu" size="icon" variant="outline" />}>
        ☰
      </DropdownMenuTrigger>
      <DropdownMenuContent>
        <DropdownMenuItem onClick={() => alert("open")}>Open</DropdownMenuItem>
        <DropdownMenuItem onClick={() => alert("rename")}>
          Rename…
        </DropdownMenuItem>
        <DropdownMenuItem onClick={() => alert("duplicate")}>
          Duplicate
        </DropdownMenuItem>
        <DropdownMenuItem onClick={() => alert("share")}>
          Share…
        </DropdownMenuItem>
        <DropdownMenuItem onClick={() => alert("delete")}>
          Delete…
        </DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

## Installation

```bash
pnpm dlx shadcn@latest add https://prototyper-ui.com/r/menu.json
```

This will add the following files to your project:

- `components/ui/menu.tsx`

## Usage

```tsx
import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuItem,
} from "@/components/ui/menu"

<DropdownMenu>
  <DropdownMenuTrigger>Open Menu</DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuItem>Item 1</DropdownMenuItem>
    <DropdownMenuItem>Item 2</DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>
```

## Anatomy

```tsx
<DropdownMenu>
  <DropdownMenuTrigger />
  <DropdownMenuContent>
    <DropdownMenuLabel />
    <DropdownMenuSeparator />
    <DropdownMenuGroup>
      <DropdownMenuItem />
    </DropdownMenuGroup>
    <DropdownMenuCheckboxItem />
    <DropdownMenuRadioGroup>
      <DropdownMenuRadioItem />
    </DropdownMenuRadioGroup>
    <DropdownMenuSub>
      <DropdownMenuSubTrigger />
      <DropdownMenuSubContent>
        <DropdownMenuItem />
      </DropdownMenuSubContent>
    </DropdownMenuSub>
  </DropdownMenuContent>
</DropdownMenu>
```

| Sub-component                | `data-slot`                      | Purpose                                    | Required |
| ---------------------------- | -------------------------------- | ------------------------------------------ | -------- |
| `DropdownMenu`               | `dropdown-menu`                  | Root provider, manages open/close state    | Yes      |
| `DropdownMenuTrigger`        | `dropdown-menu-trigger`          | Button that opens the menu                 | Yes      |
| `DropdownMenuPortal`         | `dropdown-menu-portal`           | Renders children into a portal             | No       |
| `DropdownMenuContent`        | `dropdown-menu-content`          | The popup panel containing menu items      | Yes      |
| `DropdownMenuGroup`          | `dropdown-menu-group`            | Groups related menu items                  | No       |
| `DropdownMenuLabel`          | `dropdown-menu-label`            | Non-interactive label for a group          | No       |
| `DropdownMenuItem`           | `dropdown-menu-item`             | Individual actionable menu item            | Yes      |
| `DropdownMenuCheckboxItem`   | `dropdown-menu-checkbox-item`    | Toggleable checkbox menu item              | No       |
| `DropdownMenuRadioGroup`     | `dropdown-menu-radio-group`      | Groups radio menu items                    | No       |
| `DropdownMenuRadioItem`      | `dropdown-menu-radio-item`       | Radio-selectable menu item                 | No       |
| `DropdownMenuSeparator`      | `dropdown-menu-separator`        | Visual separator between items             | No       |
| `DropdownMenuShortcut`       | `dropdown-menu-shortcut`         | Keyboard shortcut hint text                | No       |
| `DropdownMenuSub`            | `dropdown-menu-sub`              | Root for a submenu                         | No       |
| `DropdownMenuSubTrigger`     | `dropdown-menu-sub-trigger`      | Item that opens a submenu                  | No       |
| `DropdownMenuSubContent`     | `dropdown-menu-sub-content`      | Popup panel for a submenu                  | No       |

## Examples

### Content
```tsx
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "@/components/ui/menu"

import { Button } from "@/components/ui/button"

export default function MenuContent() {
  let items = [
    { id: 1, name: "New" },
    { id: 2, name: "Open" },
    { id: 3, name: "Close" },
    { id: 4, name: "Save" },
    { id: 5, name: "Duplicate" },
    { id: 6, name: "Rename" },
    { id: 7, name: "Move" },
  ]

  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>
        Actions
      </DropdownMenuTrigger>
      <DropdownMenuContent>
        {items.map((item) => (
          <DropdownMenuItem key={item.id}>{item.name}</DropdownMenuItem>
        ))}
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

### Disabled Items
```tsx
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "@/components/ui/menu"

import { Button } from "@/components/ui/button"

export default function MenuDisabledItems() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>
        Actions
      </DropdownMenuTrigger>
      <DropdownMenuContent>
        <DropdownMenuItem>Copy</DropdownMenuItem>
        <DropdownMenuItem>Cut</DropdownMenuItem>
        <DropdownMenuItem disabled>Paste</DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

### Disabled Keys
```tsx
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "@/components/ui/menu"

import { Button } from "@/components/ui/button"

export default function MenuDisabledKeys() {
  let items = [
    { id: 1, name: "New" },
    { id: 2, name: "Open" },
    { id: 3, name: "Close" },
    { id: 4, name: "Save" },
    { id: 5, name: "Duplicate" },
    { id: 6, name: "Rename" },
    { id: 7, name: "Move" },
  ]

  let disabledKeys = [4, 6]

  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>
        Actions
      </DropdownMenuTrigger>
      <DropdownMenuContent>
        {items.map((item) => (
          <DropdownMenuItem key={item.id} disabled={disabledKeys.includes(item.id)}>
            {item.name}
          </DropdownMenuItem>
        ))}
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

### Links
```tsx
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "@/components/ui/menu"

import { Button } from "@/components/ui/button"

export default function MenuLinks() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>
        Links
      </DropdownMenuTrigger>
      <DropdownMenuContent>
        <DropdownMenuItem>
          <a href="https://adobe.com/" target="_blank" rel="noopener noreferrer">
            Adobe
          </a>
        </DropdownMenuItem>
        <DropdownMenuItem>
          <a href="https://apple.com/" target="_blank" rel="noopener noreferrer">
            Apple
          </a>
        </DropdownMenuItem>
        <DropdownMenuItem>
          <a href="https://google.com/" target="_blank" rel="noopener noreferrer">
            Google
          </a>
        </DropdownMenuItem>
        <DropdownMenuItem>
          <a href="https://microsoft.com/" target="_blank" rel="noopener noreferrer">
            Microsoft
          </a>
        </DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

### Long Press
```tsx
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "@/components/ui/menu"

import { Button } from "@/components/ui/button"

export default function MenuLongPress() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger
        render={
          <Button
            variant="outline"
            onClick={() => alert("crop")}
            onContextMenu={(e) => e.preventDefault()}
          />
        }
      >
        Crop
      </DropdownMenuTrigger>
      <DropdownMenuContent>
        <DropdownMenuItem>Rotate</DropdownMenuItem>
        <DropdownMenuItem>Slice</DropdownMenuItem>
        <DropdownMenuItem>Clone stamp</DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

### Reusable
```tsx
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "@/components/ui/menu"

import { Button } from "@/components/ui/button"

function ProtoMenu({
  label,
  variant = "outline",
  children,
}: {
  label: string
  variant?: "outline" | "default" | "ghost" | "secondary" | "destructive" | "link"
  children: React.ReactNode
}) {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant={variant} />}>
        {label}
      </DropdownMenuTrigger>
      <DropdownMenuContent>{children}</DropdownMenuContent>
    </DropdownMenu>
  )
}

export default function MenuReusable() {
  return (
    <ProtoMenu variant="outline" label="Edit">
      <DropdownMenuItem>Cut</DropdownMenuItem>
      <DropdownMenuItem>Copy</DropdownMenuItem>
      <DropdownMenuItem>Paste</DropdownMenuItem>
      <DropdownMenuItem>Delete Item</DropdownMenuItem>
    </ProtoMenu>
  )
}
```

### Sections
```tsx
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuTrigger,
} from "@/components/ui/menu"

import { Button } from "@/components/ui/button"

export default function MenuSections() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>
        Actions
      </DropdownMenuTrigger>
      <DropdownMenuContent>
        <DropdownMenuGroup>
          <DropdownMenuLabel>Styles</DropdownMenuLabel>
          <DropdownMenuItem>Bold</DropdownMenuItem>
          <DropdownMenuItem>Underline</DropdownMenuItem>
        </DropdownMenuGroup>
        <DropdownMenuGroup>
          <DropdownMenuLabel>Align</DropdownMenuLabel>
          <DropdownMenuItem>Left</DropdownMenuItem>
          <DropdownMenuItem>Middle</DropdownMenuItem>
          <DropdownMenuItem>Right</DropdownMenuItem>
        </DropdownMenuGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

### Sections Dynamic
```tsx
"use client"

import React from "react"
import {
  DropdownMenu,
  DropdownMenuCheckboxItem,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuLabel,
  DropdownMenuTrigger,
} from "@/components/ui/menu"

import { Button } from "@/components/ui/button"

export default function MenuSectionsDynamic() {
  let [selected, setSelected] = React.useState<Record<number, boolean>>({
    1: true,
    3: true,
  })

  let openWindows = [
    {
      name: "Left Panel",
      id: "left",
      children: [{ id: 1, name: "Final Copy (1)" }],
    },
    {
      name: "Right Panel",
      id: "right",
      children: [
        { id: 2, name: "index.ts" },
        { id: 3, name: "package.json" },
        { id: 4, name: "license.txt" },
      ],
    },
  ]

  const handleCheckedChange = (id: number, checked: boolean) => {
    setSelected((prev) => ({ ...prev, [id]: checked }))
  }

  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>
        Window
      </DropdownMenuTrigger>
      <DropdownMenuContent>
        {openWindows.map((section) => (
          <DropdownMenuGroup key={section.id}>
            <DropdownMenuLabel>{section.name}</DropdownMenuLabel>
            {section.children.map((item) => (
              <DropdownMenuCheckboxItem
                key={item.id}
                checked={selected[item.id] || false}
                onCheckedChange={(checked) =>
                  handleCheckedChange(item.id, checked)
                }
              >
                {item.name}
              </DropdownMenuCheckboxItem>
            ))}
          </DropdownMenuGroup>
        ))}
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

### Selection Multiple
```tsx
"use client"

import React from "react"
import {
  DropdownMenu,
  DropdownMenuCheckboxItem,
  DropdownMenuContent,
  DropdownMenuTrigger,
} from "@/components/ui/menu"

import { Button } from "@/components/ui/button"

export default function MenuSelectionMultiple() {
  let [sidebar, setSidebar] = React.useState(true)
  let [searchbar, setSearchbar] = React.useState(false)
  let [tools, setTools] = React.useState(false)
  let [console, setConsole] = React.useState(true)

  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>
        View
      </DropdownMenuTrigger>
      <DropdownMenuContent>
        <DropdownMenuCheckboxItem checked={sidebar} onCheckedChange={setSidebar}>
          Sidebar
        </DropdownMenuCheckboxItem>
        <DropdownMenuCheckboxItem
          checked={searchbar}
          onCheckedChange={setSearchbar}
        >
          Searchbar
        </DropdownMenuCheckboxItem>
        <DropdownMenuCheckboxItem checked={tools} onCheckedChange={setTools}>
          Tools
        </DropdownMenuCheckboxItem>
        <DropdownMenuCheckboxItem checked={console} onCheckedChange={setConsole}>
          Console
        </DropdownMenuCheckboxItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

### Selection Single
```tsx
"use client"

import React from "react"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuTrigger,
} from "@/components/ui/menu"

import { Button } from "@/components/ui/button"

export default function MenuSelectionSingle() {
  let [selected, setSelected] = React.useState("center")

  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>
        Align
      </DropdownMenuTrigger>
      <DropdownMenuContent>
        <DropdownMenuRadioGroup value={selected} onValueChange={setSelected}>
          <DropdownMenuRadioItem value="left">Left</DropdownMenuRadioItem>
          <DropdownMenuRadioItem value="center">Center</DropdownMenuRadioItem>
          <DropdownMenuRadioItem value="right">Right</DropdownMenuRadioItem>
        </DropdownMenuRadioGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

### Separators
```tsx
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@/components/ui/menu"

import { Button } from "@/components/ui/button"

export default function MenuSeparators() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>
        Actions
      </DropdownMenuTrigger>
      <DropdownMenuContent>
        <DropdownMenuItem>New…</DropdownMenuItem>
        <DropdownMenuItem>Open…</DropdownMenuItem>
        <DropdownMenuSeparator />
        <DropdownMenuItem>Save</DropdownMenuItem>
        <DropdownMenuItem>Save as…</DropdownMenuItem>
        <DropdownMenuItem>Rename…</DropdownMenuItem>
        <DropdownMenuSeparator />
        <DropdownMenuItem>Page setup…</DropdownMenuItem>
        <DropdownMenuItem>Print…</DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

### Sub Menu
```tsx
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSub,
  DropdownMenuSubContent,
  DropdownMenuSubTrigger,
  DropdownMenuTrigger,
} from "@/components/ui/menu"

import { Button } from "@/components/ui/button"

export default function MenuSubMenus() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>
        Actions
      </DropdownMenuTrigger>
      <DropdownMenuContent>
        <DropdownMenuItem>Copy</DropdownMenuItem>
        <DropdownMenuItem>Cut</DropdownMenuItem>
        <DropdownMenuItem>Delete</DropdownMenuItem>
        <DropdownMenuSub>
          <DropdownMenuSubTrigger>Share</DropdownMenuSubTrigger>
          <DropdownMenuSubContent>
            <DropdownMenuItem>SMS</DropdownMenuItem>
            <DropdownMenuItem>Twitter</DropdownMenuItem>
            <DropdownMenuSub>
              <DropdownMenuSubTrigger>Email</DropdownMenuSubTrigger>
              <DropdownMenuSubContent>
                <DropdownMenuItem>Work</DropdownMenuItem>
                <DropdownMenuItem>Personal</DropdownMenuItem>
              </DropdownMenuSubContent>
            </DropdownMenuSub>
          </DropdownMenuSubContent>
        </DropdownMenuSub>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

### Sub Menu Dynamic
```tsx
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSub,
  DropdownMenuSubContent,
  DropdownMenuSubTrigger,
  DropdownMenuTrigger,
} from "@/components/ui/menu"

import { Button } from "@/components/ui/button"

type MenuItem = {
  id: string
  name: string
  children?: MenuItem[]
}

export default function MenuSubMenuDynamic() {
  let items: MenuItem[] = [
    { id: "cut", name: "Cut" },
    { id: "copy", name: "Copy" },
    { id: "delete", name: "Delete" },
    {
      id: "share",
      name: "Share",
      children: [
        { id: "sms", name: "SMS" },
        { id: "twitter", name: "Twitter" },
        {
          id: "email",
          name: "Email",
          children: [
            { id: "work", name: "Work" },
            { id: "personal", name: "Personal" },
          ],
        },
      ],
    },
  ]

  function renderSubmenu(item: MenuItem) {
    if (item.children) {
      return (
        <DropdownMenuSub key={item.id}>
          <DropdownMenuSubTrigger>{item.name}</DropdownMenuSubTrigger>
          <DropdownMenuSubContent>
            {item.children.map((child) => renderSubmenu(child))}
          </DropdownMenuSubContent>
        </DropdownMenuSub>
      )
    } else {
      return <DropdownMenuItem key={item.id}>{item.name}</DropdownMenuItem>
    }
  }

  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>
        Actions
      </DropdownMenuTrigger>
      <DropdownMenuContent>
        {items.map((item) => renderSubmenu(item))}
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

### Text Slots
```tsx
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuShortcut,
  DropdownMenuTrigger,
} from "@/components/ui/menu"

import { Button } from "@/components/ui/button"

export default function MenuTextSlots() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>
        Actions
      </DropdownMenuTrigger>
      <DropdownMenuContent>
        <DropdownMenuItem className="flex gap-2">
          <span className="flex flex-col items-start gap-1">
            <span>Copy</span>
            <span className="text-sm text-muted-foreground">
              Copy the selected text
            </span>
          </span>
          <DropdownMenuShortcut>⌘C</DropdownMenuShortcut>
        </DropdownMenuItem>
        <DropdownMenuItem>
          <span className="flex flex-col items-start gap-1">
            <span>Cut</span>
            <span className="text-sm text-muted-foreground">
              Cut the selected text
            </span>
          </span>
          <DropdownMenuShortcut>⌘X</DropdownMenuShortcut>
        </DropdownMenuItem>
        <DropdownMenuItem>
          <span className="flex flex-col items-start gap-1">
            <span>Paste</span>
            <span className="text-sm text-muted-foreground">
              Paste the copied text
            </span>
          </span>
          <DropdownMenuShortcut>⌘V</DropdownMenuShortcut>
        </DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

## Styling

### Data Slots

Use `data-slot` attributes to target specific parts of the menu:

| Slot name                      | Element                          |
| ------------------------------ | -------------------------------- |
| `dropdown-menu`                | Root provider (no DOM rendered)  |
| `dropdown-menu-trigger`        | The trigger button               |
| `dropdown-menu-portal`         | Portal wrapper                   |
| `dropdown-menu-content`        | The popup panel                  |
| `dropdown-menu-group`          | Group wrapper                    |
| `dropdown-menu-label`          | Group label                      |
| `dropdown-menu-item`           | Individual menu item             |
| `dropdown-menu-checkbox-item`  | Checkbox menu item               |
| `dropdown-menu-radio-group`    | Radio group wrapper              |
| `dropdown-menu-radio-item`     | Radio menu item                  |
| `dropdown-menu-separator`      | Visual separator line            |
| `dropdown-menu-shortcut`       | Keyboard shortcut text           |
| `dropdown-menu-sub`            | Submenu root                     |
| `dropdown-menu-sub-trigger`    | Submenu trigger item             |
| `dropdown-menu-sub-content`    | Submenu popup panel              |

### Customization Examples

```css
/* Change menu item highlight color */
[data-slot="dropdown-menu-item"][data-highlighted] {
  @apply bg-primary text-primary-foreground;
}

/* Wider menu popup */
[data-slot="dropdown-menu-content"] {
  @apply min-w-[12rem];
}
```

```tsx
{/* Override styles via className */}
<DropdownMenuContent className="w-64">
  <DropdownMenuItem className="font-medium">
    Custom Item
  </DropdownMenuItem>
</DropdownMenuContent>
```

## API Reference

### DropdownMenu

Root component that manages open/close state.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | - | Controlled open state |
| `onOpenChange` | `(open: boolean) => void` | - | Callback when open state changes |

All [Base UI Menu.Root props](https://base-ui.com/react/components/menu) are forwarded via `...props`.

### DropdownMenuTrigger

Button that opens the menu when clicked.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Menu.Trigger props](https://base-ui.com/react/components/menu) are forwarded via `...props`.

### DropdownMenuContent

The popup panel containing menu items, rendered inside a portal with a positioner.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"start" \| "center" \| "end"` | `"start"` | Alignment relative to the trigger |
| `alignOffset` | `number` | `0` | Offset from the alignment edge |
| `side` | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | Preferred side relative to trigger |
| `sideOffset` | `number` | `4` | Gap between trigger and popup |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Menu content |

All [Base UI Menu.Popup props](https://base-ui.com/react/components/menu) are forwarded via `...props`.

### DropdownMenuGroup

Groups related menu items together.

All [Base UI Menu.Group props](https://base-ui.com/react/components/menu) are forwarded via `...props`.

### DropdownMenuLabel

Non-interactive label for a group of menu items.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `inset` | `boolean` | - | Adds left padding to align with items that have icons |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Menu.GroupLabel props](https://base-ui.com/react/components/menu) are forwarded via `...props`.

### DropdownMenuItem

Individual actionable menu item.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "destructive"` | `"default"` | Visual style variant |
| `inset` | `boolean` | - | Adds left padding to align with items that have icons |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Menu.Item props](https://base-ui.com/react/components/menu) are forwarded via `...props`.

### DropdownMenuCheckboxItem

Toggleable checkbox menu item with a check indicator.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` | - | Whether the item is checked |
| `inset` | `boolean` | - | Adds left padding to align with items that have icons |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Item content |

All [Base UI Menu.CheckboxItem props](https://base-ui.com/react/components/menu) are forwarded via `...props`.

### DropdownMenuRadioGroup

Groups radio menu items for single-selection behavior.

All [Base UI Menu.RadioGroup props](https://base-ui.com/react/components/menu) are forwarded via `...props`.

### DropdownMenuRadioItem

Radio-selectable menu item within a radio group.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `inset` | `boolean` | - | Adds left padding to align with items that have icons |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Item content |

All [Base UI Menu.RadioItem props](https://base-ui.com/react/components/menu) are forwarded via `...props`.

### DropdownMenuSeparator

Visual separator between menu items or groups.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Menu.Separator props](https://base-ui.com/react/components/menu) are forwarded via `...props`.

### DropdownMenuShortcut

Displays a keyboard shortcut hint aligned to the right of a menu item.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All standard `span` props are forwarded via `...props`.

### DropdownMenuSub

Root provider for a submenu.

All [Base UI Menu.SubmenuRoot props](https://base-ui.com/react/components/menu) are forwarded via `...props`.

### DropdownMenuSubTrigger

Menu item that opens a submenu on hover or keyboard navigation.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `inset` | `boolean` | - | Adds left padding to align with items that have icons |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Trigger content |

All [Base UI Menu.SubmenuTrigger props](https://base-ui.com/react/components/menu) are forwarded via `...props`.

### DropdownMenuSubContent

Popup panel for a submenu, rendered inside a portal with a positioner.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"start" \| "center" \| "end"` | `"start"` | Alignment relative to the trigger |
| `alignOffset` | `number` | `-3` | Offset from the alignment edge |
| `side` | `"top" \| "bottom" \| "left" \| "right"` | `"right"` | Preferred side relative to trigger |
| `sideOffset` | `number` | `0` | Gap between trigger and popup |
| `className` | `string` | - | Additional CSS classes |

All `DropdownMenuContent` props are forwarded via `...props`.

## Accessibility

### Keyboard Interactions

| Key              | Action                                                    |
| ---------------- | --------------------------------------------------------- |
| `Space`          | Activates the focused menu item                           |
| `Enter`          | Activates the focused menu item                           |
| `ArrowDown`      | Moves focus to the next menu item                         |
| `ArrowUp`        | Moves focus to the previous menu item                     |
| `ArrowRight`     | Opens a submenu when focused on a sub-trigger             |
| `ArrowLeft`      | Closes a submenu and returns focus to the parent trigger  |
| `Escape`         | Closes the menu                                           |
| `Home`           | Moves focus to the first menu item                        |
| `End`            | Moves focus to the last menu item                         |

### ARIA Attributes

- `DropdownMenuContent` receives `role="menu"`.
- `DropdownMenuItem` receives `role="menuitem"`.
- `DropdownMenuCheckboxItem` receives `role="menuitemcheckbox"` with `aria-checked`.
- `DropdownMenuRadioItem` receives `role="menuitemradio"` with `aria-checked`.
- `DropdownMenuSub` content receives `role="menu"` for nested menus.
- `data-disabled` is set on disabled items, which sets `aria-disabled`.
- Focus is managed within the menu and returns to the trigger when the menu closes.
</page>

<page url="https://prototyper-ui.com/docs/components/meter" slug="components/meter">
# Meter
> A meter displaying a value within a known range
URL: https://prototyper-ui.com/docs/components/meter
Base UI reference: https://base-ui.com/react/components/meter
```tsx
"use client"

import React from "react"

import { Meter, MeterIndicator, MeterLabel, MeterTrack, MeterValue } from "@/components/ui/meter"

export default function MeterDemo() {
  const [progress, setProgress] = React.useState(13)

  React.useEffect(() => {
    const timer = setTimeout(() => setProgress(66), 500)
    return () => clearTimeout(timer)
  }, [])

  return (
    <Meter value={progress} className="w-3/5">
      <div className="flex w-full justify-between">
        <MeterLabel>Storage space</MeterLabel>
        <MeterValue />
      </div>
      <MeterTrack>
        <MeterIndicator />
      </MeterTrack>
    </Meter>
  )
}
```

## Installation

```bash
pnpm dlx shadcn@latest add https://prototyper-ui.com/r/meter.json
```

This will add the following files to your project:

- `components/ui/meter.tsx`

## Usage

```tsx
import {
  Meter,
  MeterTrack,
  MeterIndicator,
  MeterLabel,
  MeterValue,
} from "@/components/ui/meter"

<Meter value={60}>
  <MeterLabel>Storage</MeterLabel>
  <MeterTrack>
    <MeterIndicator />
  </MeterTrack>
</Meter>
```

## Anatomy

```tsx
<Meter>
  <MeterLabel />
  <MeterValue />
  <MeterTrack>
    <MeterIndicator />
  </MeterTrack>
</Meter>
```

| Sub-component    | `data-slot`       | Purpose                                 | Required |
| ---------------- | ----------------- | --------------------------------------- | -------- |
| `Meter`          | `meter`           | Root provider, manages value state      | Yes      |
| `MeterTrack`     | `meter-track`     | Background track for the indicator      | Yes      |
| `MeterIndicator` | `meter-indicator` | Filled portion representing the value   | Yes      |
| `MeterLabel`     | `meter-label`     | Accessible label for the meter          | No       |
| `MeterValue`     | `meter-value`     | Displays the current value as text      | No       |

## Examples

### Custom Format
```tsx
import { Meter, MeterIndicator, MeterLabel, MeterTrack } from "@/components/ui/meter"

export default function MeterCustomFormat() {
  return (
    <Meter value={54} className="w-3/5">
      <div className="flex w-full justify-between">
        <MeterLabel>Space used</MeterLabel>
        <span className="text-sm text-muted-foreground">54 of 60GB</span>
      </div>
      <MeterTrack>
        <MeterIndicator />
      </MeterTrack>
    </Meter>
  )
}
```

### Reusable
```tsx
import { Meter, MeterIndicator, MeterLabel, MeterTrack, MeterValue } from "@/components/ui/meter"

export default function MeterReusable() {
  return (
    <Meter value={80} className="w-3/5">
      <div className="flex w-full justify-between">
        <MeterLabel>Storage space</MeterLabel>
        <MeterValue />
      </div>
      <MeterTrack>
        <MeterIndicator />
      </MeterTrack>
    </Meter>
  )
}
```

### Value Format
```tsx
import { Meter, MeterIndicator, MeterLabel, MeterTrack, MeterValue } from "@/components/ui/meter"

export default function MeterValueFormat() {
  return (
    <Meter value={60} className="w-3/5">
      <div className="flex w-full justify-between">
        <MeterLabel>Currency</MeterLabel>
        <MeterValue />
      </div>
      <MeterTrack>
        <MeterIndicator />
      </MeterTrack>
    </Meter>
  )
}
```

## Styling

### Data Slots

Use `data-slot` attributes to target specific parts of the meter:

| Slot name         | Element                              |
| ----------------- | ------------------------------------ |
| `meter`           | Root wrapper                         |
| `meter-track`     | Background track bar                 |
| `meter-indicator` | Filled indicator bar                 |
| `meter-label`     | Label text                           |
| `meter-value`     | Value text                           |

### Customization Examples

```css
/* Make the meter track taller */
[data-slot="meter-track"] {
  @apply h-4 rounded-lg;
}

/* Custom indicator color */
[data-slot="meter-indicator"] {
  @apply bg-gradient-to-r from-blue-500 to-purple-500;
}
```

```tsx
{/* Override track color via className */}
<MeterTrack className="bg-blue-100" color="default">
  <MeterIndicator className="bg-blue-500" />
</MeterTrack>
```

## API Reference

### Meter

Root component that provides meter value context.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` | - | Current value of the meter |
| `min` | `number` | `0` | Minimum value |
| `max` | `number` | `100` | Maximum value |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Meter content |

All [Base UI Meter.Root props](https://base-ui.com/react/components/meter) are forwarded via `...props`.

### MeterTrack

Background track that contains the indicator.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `color` | `"default" \| "success" \| "warning" \| "destructive"` | `"default"` | Color variant for the track |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Track content (typically MeterIndicator) |

All [Base UI Meter.Track props](https://base-ui.com/react/components/meter) are forwarded via `...props`.

### MeterIndicator

The filled portion of the track representing the current value.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `color` | `"default" \| "success" \| "warning" \| "destructive"` | `"default"` | Color variant for the indicator |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Meter.Indicator props](https://base-ui.com/react/components/meter) are forwarded via `...props`.

### MeterLabel

Accessible label for the meter.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Label text |

All [Base UI Meter.Label props](https://base-ui.com/react/components/meter) are forwarded via `...props`.

### MeterValue

Displays the current meter value as formatted text.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Custom value rendering |

All [Base UI Meter.Value props](https://base-ui.com/react/components/meter) are forwarded via `...props`.

### meterTrackVariants

A `cva` helper exported for applying meter track styles outside of the `<MeterTrack>` component.

```tsx
import { meterTrackVariants } from "@/components/ui/meter"

<div className={meterTrackVariants({ color: "success" })}>Custom track</div>
```

### meterIndicatorVariants

A `cva` helper exported for applying meter indicator styles outside of the `<MeterIndicator>` component.

```tsx
import { meterIndicatorVariants } from "@/components/ui/meter"

<div className={meterIndicatorVariants({ color: "warning" })}>Custom indicator</div>
```

## Accessibility

### Keyboard Interactions

The meter is a non-interactive display element and does not have keyboard interactions. Focus management is handled by surrounding interactive elements.

### ARIA Attributes

- The meter renders with `role="meter"` via the Base UI primitive.
- `aria-valuenow` reflects the current value.
- `aria-valuemin` and `aria-valuemax` define the range.
- `aria-labelledby` is automatically linked to `MeterLabel` when present.
- Screen readers announce the meter value and its label.
</page>

<page url="https://prototyper-ui.com/docs/components/numberfield" slug="components/numberfield">
# NumberField
> A number input with increment/decrement controls built on Base UI
URL: https://prototyper-ui.com/docs/components/numberfield
Base UI reference: https://base-ui.com/react/components/number-field
```tsx
import {
  NumberField,
  NumberFieldGroup,
  NumberFieldInput,
  NumberFieldSteppers,
} from "@/components/ui/numberfield"
import { FieldLabel } from "@/components/ui/field"

export default function NumberFieldDemo() {
  return (
    <NumberField defaultValue={1024} min={0}>
      <FieldLabel>Width</FieldLabel>
      <NumberFieldGroup>
        <NumberFieldInput />
        <NumberFieldSteppers />
      </NumberFieldGroup>
    </NumberField>
  )
}
```

## Installation

```bash
pnpm dlx shadcn@latest add https://prototyper-ui.com/r/numberfield.json
```

This will add the following files to your project:

- `components/ui/numberfield.tsx`

> **Note:** This component depends on [Field](/docs/components/field). It will be installed automatically.

## Usage

```tsx
import {
  NumberField,
  NumberFieldGroup,
  NumberFieldInput,
  NumberFieldSteppers,
} from "@/components/ui/numberfield"

<NumberField>
  <NumberFieldGroup>
    <NumberFieldInput />
    <NumberFieldSteppers />
  </NumberFieldGroup>
</NumberField>
```

## Anatomy

```tsx
<NumberField>
  <FieldLabel />
  <NumberFieldGroup>
    <NumberFieldInput />
    <NumberFieldSteppers />
  </NumberFieldGroup>
  <FieldDescription />
  <FieldError />
</NumberField>
```

Or with individual step buttons:

```tsx
<NumberField>
  <NumberFieldGroup>
    <NumberFieldDecrement />
    <NumberFieldInput />
    <NumberFieldIncrement />
  </NumberFieldGroup>
</NumberField>
```

| Sub-component              | `data-slot`                    | Purpose                                     | Required |
| -------------------------- | ------------------------------ | ------------------------------------------- | -------- |
| `NumberField`              | `number-field`                 | Root provider, manages value state           | Yes      |
| `NumberFieldGroup`         | `number-field-group`           | Visual container for input and steppers      | Yes      |
| `NumberFieldInput`         | `number-field-input`           | The numeric input element                    | Yes      |
| `NumberFieldIncrement`     | `number-field-increment`       | Button to increase the value                 | No       |
| `NumberFieldDecrement`     | `number-field-decrement`       | Button to decrease the value                 | No       |
| `NumberFieldSteppers`      | `number-field-steppers`        | Convenience wrapper with increment/decrement | No       |
| `NumberFieldScrubArea`     | `number-field-scrub-area`      | Drag-to-scrub area for value adjustment      | No       |
| `NumberFieldScrubAreaCursor` | `number-field-scrub-area-cursor` | Custom cursor for the scrub area          | No       |

## Examples

### Currency
```tsx
import {
  NumberField,
  NumberFieldGroup,
  NumberFieldInput,
  NumberFieldSteppers,
} from "@/components/ui/numberfield"
import { FieldLabel } from "@/components/ui/field"

export default function NumberFieldCurrency() {
  return (
    <NumberField
      defaultValue={45}
      format={{
        style: "currency",
        currency: "EUR",
        currencyDisplay: "code",
        currencySign: "accounting",
      }}
    >
      <FieldLabel>Transaction amount</FieldLabel>
      <NumberFieldGroup>
        <NumberFieldInput />
        <NumberFieldSteppers />
      </NumberFieldGroup>
    </NumberField>
  )
}
```

### Description
```tsx
import {
  NumberField,
  NumberFieldGroup,
  NumberFieldInput,
  NumberFieldSteppers,
} from "@/components/ui/numberfield"
import { FieldLabel } from "@/components/ui/field"

export default function NumberFieldDescription() {
  return (
    <NumberField className="group" name="width" required>
      <FieldLabel>Width</FieldLabel>
      <NumberFieldGroup>
        <NumberFieldInput />
        <NumberFieldSteppers />
      </NumberFieldGroup>
      <p className="text-sm text-muted-foreground">
        Enter a width in centimeters.
      </p>
    </NumberField>
  )
}
```

### Disabled
```tsx
import {
  NumberField,
  NumberFieldGroup,
  NumberFieldInput,
  NumberFieldSteppers,
} from "@/components/ui/numberfield"
import { FieldLabel } from "@/components/ui/field"

export default function NumberFieldDisabled() {
  return (
    <NumberField disabled value={25}>
      <FieldLabel>Disabled</FieldLabel>
      <NumberFieldGroup>
        <NumberFieldInput />
        <NumberFieldSteppers />
      </NumberFieldGroup>
    </NumberField>
  )
}
```

### Formatting
```tsx
import {
  NumberField,
  NumberFieldGroup,
  NumberFieldInput,
  NumberFieldSteppers,
} from "@/components/ui/numberfield"
import { FieldLabel } from "@/components/ui/field"

export default function NumberFieldFormatting() {
  return (
    <NumberField
      defaultValue={0}
      format={{
        signDisplay: "exceptZero",
        minimumFractionDigits: 1,
        maximumFractionDigits: 2,
      }}
    >
      <FieldLabel>Adjust exposure</FieldLabel>
      <NumberFieldGroup>
        <NumberFieldInput />
        <NumberFieldSteppers />
      </NumberFieldGroup>
    </NumberField>
  )
}
```

### Percentages
```tsx
import {
  NumberField,
  NumberFieldGroup,
  NumberFieldInput,
  NumberFieldSteppers,
} from "@/components/ui/numberfield"
import { FieldLabel } from "@/components/ui/field"

export default function NumberFieldPercentages() {
  return (
    <NumberField
      defaultValue={0.05}
      format={{
        style: "percent",
      }}
    >
      <FieldLabel>Sales tax</FieldLabel>
      <NumberFieldGroup>
        <NumberFieldInput />
        <NumberFieldSteppers />
      </NumberFieldGroup>
    </NumberField>
  )
}
```

### Read Only
```tsx
import {
  NumberField,
  NumberFieldGroup,
  NumberFieldInput,
  NumberFieldSteppers,
} from "@/components/ui/numberfield"
import { FieldLabel } from "@/components/ui/field"

export default function NumberFieldReadonly() {
  return (
    <NumberField readOnly value={32}>
      <FieldLabel>Read only</FieldLabel>
      <NumberFieldGroup>
        <NumberFieldInput />
        <NumberFieldSteppers />
      </NumberFieldGroup>
    </NumberField>
  )
}
```

### Reusable
```tsx
import {
  NumberField,
  NumberFieldGroup,
  NumberFieldInput,
  NumberFieldSteppers,
} from "@/components/ui/numberfield"
import { FieldDescription, FieldLabel } from "@/components/ui/field"

export default function NumberfieldReusable() {
  return (
    <NumberField required>
      <FieldLabel>Cookies</FieldLabel>
      <NumberFieldGroup>
        <NumberFieldInput />
        <NumberFieldSteppers />
      </NumberFieldGroup>
      <FieldDescription>Please enter a number</FieldDescription>
    </NumberField>
  )
}
```

### Step Values
```tsx
import {
  NumberField,
  NumberFieldGroup,
  NumberFieldInput,
  NumberFieldSteppers,
} from "@/components/ui/numberfield"
import { FieldLabel } from "@/components/ui/field"

export default function NumberFieldStepValues() {
  return (
    <div className="flex flex-col gap-2">
      <NumberField step={10}>
        <FieldLabel>Step</FieldLabel>
        <NumberFieldGroup>
          <NumberFieldInput />
          <NumberFieldSteppers />
        </NumberFieldGroup>
      </NumberField>
      <NumberField min={2} step={3}>
        <FieldLabel>Step + minValue</FieldLabel>
        <NumberFieldGroup>
          <NumberFieldInput />
          <NumberFieldSteppers />
        </NumberFieldGroup>
      </NumberField>
      <NumberField min={2} max={21} step={3}>
        <FieldLabel>Step + minValue + maxValue</FieldLabel>
        <NumberFieldGroup>
          <NumberFieldInput />
          <NumberFieldSteppers />
        </NumberFieldGroup>
      </NumberField>
    </div>
  )
}
```

### Units
```tsx
import {
  NumberField,
  NumberFieldGroup,
  NumberFieldInput,
  NumberFieldSteppers,
} from "@/components/ui/numberfield"
import { FieldLabel } from "@/components/ui/field"

export default function NumberFieldUnits() {
  return (
    <NumberField
      defaultValue={4}
      format={{
        style: "unit",
        unit: "inch",
        unitDisplay: "long",
      }}
    >
      <FieldLabel>Package width</FieldLabel>
      <NumberFieldGroup>
        <NumberFieldInput />
        <NumberFieldSteppers />
      </NumberFieldGroup>
    </NumberField>
  )
}
```

### Validation
```tsx
import {
  NumberField,
  NumberFieldGroup,
  NumberFieldInput,
  NumberFieldSteppers,
} from "@/components/ui/numberfield"
import { FieldLabel } from "@/components/ui/field"

export default function NumberFieldValidation() {
  return (
    <NumberField min={0}>
      <FieldLabel>Enter your age</FieldLabel>
      <NumberFieldGroup>
        <NumberFieldInput />
        <NumberFieldSteppers />
      </NumberFieldGroup>
    </NumberField>
  )
}
```

### Validation Error
```tsx
import {
  NumberField,
  NumberFieldGroup,
  NumberFieldInput,
  NumberFieldSteppers,
} from "@/components/ui/numberfield"
import { Button } from "@/components/ui/button"
import { FieldError, FieldLabel } from "@/components/ui/field"

export default function NumberFieldValidationError() {
  return (
    <form className="flex flex-col gap-2">
      <NumberField className="group" name="width" required>
        <FieldLabel>Width</FieldLabel>
        <NumberFieldGroup>
          <NumberFieldInput />
          <NumberFieldSteppers />
        </NumberFieldGroup>
        <FieldError />
      </NumberField>
      <Button type="submit" className="w-fit">
        Submit
      </Button>
    </form>
  )
}
```

## Styling

### Data Slots

Use `data-slot` attributes to target specific parts of the number field:

| Slot name                      | Element                                   |
| ------------------------------ | ----------------------------------------- |
| `number-field`                 | Root wrapper                              |
| `number-field-group`           | Visual container for input and controls   |
| `number-field-input`           | The `<input>` element                     |
| `number-field-increment`       | Increment button                          |
| `number-field-decrement`       | Decrement button                          |
| `number-field-steppers`        | Steppers container (increment + decrement)|
| `number-field-scrub-area`      | Drag-to-scrub interaction area            |
| `number-field-scrub-area-cursor` | Custom cursor for scrub area            |

### Customization Examples

```css
/* Make the number field group larger */
[data-slot="number-field-group"] {
  @apply h-12;
}

/* Style the stepper buttons */
[data-slot="number-field-increment"],
[data-slot="number-field-decrement"] {
  @apply px-2 text-primary;
}
```

```tsx
{/* Override size via className on the group */}
<NumberFieldGroup size="lg" className="rounded-lg">
  <NumberFieldInput />
  <NumberFieldSteppers />
</NumberFieldGroup>
```

## API Reference

### NumberField

Root component that manages the number field state. Built on Base UI `NumberField.Root`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI NumberField props](https://base-ui.com/react/components/number-field) are forwarded via `...props`.

### NumberFieldGroup

Visual container that wraps the input and stepper controls.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "default" \| "lg"` | `"default"` | Height of the group container |
| `className` | `string` | - | Additional CSS classes |

All [Base UI NumberField.Group props](https://base-ui.com/react/components/number-field) are forwarded via `...props`.

### NumberFieldInput

The numeric input element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI NumberField.Input props](https://base-ui.com/react/components/number-field) are forwarded via `...props`.

### NumberFieldIncrement

Button that increments the value. Renders a chevron-up icon by default.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Custom icon (replaces default chevron-up) |

All [Base UI NumberField.Increment props](https://base-ui.com/react/components/number-field) are forwarded via `...props`.

### NumberFieldDecrement

Button that decrements the value. Renders a chevron-down icon by default.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Custom icon (replaces default chevron-down) |

All [Base UI NumberField.Decrement props](https://base-ui.com/react/components/number-field) are forwarded via `...props`.

### NumberFieldSteppers

Convenience wrapper that renders increment and decrement buttons in a vertical stack.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All standard `div` props are forwarded via `...props`.

### NumberFieldScrubArea

A drag-to-scrub interaction area for adjusting the value by dragging.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI NumberField.ScrubArea props](https://base-ui.com/react/components/number-field) are forwarded via `...props`.

### NumberFieldScrubAreaCursor

Custom cursor element rendered within the scrub area.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI NumberField.ScrubAreaCursor props](https://base-ui.com/react/components/number-field) are forwarded via `...props`.

### numberFieldGroupVariants

A `cva` helper exported for applying number field group styles outside the component.

```tsx
import { numberFieldGroupVariants } from "@/components/ui/numberfield"

<div className={numberFieldGroupVariants({ size: "lg" })}>...</div>
```

## Accessibility

### Keyboard Interactions

| Key          | Action                                               |
| ------------ | ---------------------------------------------------- |
| `ArrowUp`    | Increments the value by one step                     |
| `ArrowDown`  | Decrements the value by one step                     |
| `Home`       | Sets the value to the minimum (if `min` is set)      |
| `End`        | Sets the value to the maximum (if `max` is set)      |
| `Tab`        | Moves focus into or out of the number field          |

### ARIA Attributes

- The input renders with `role="spinbutton"` via Base UI.
- `aria-valuenow`, `aria-valuemin`, and `aria-valuemax` are set automatically based on the current value and constraints.
- `aria-invalid` is set when validation fails.
- `data-disabled` is set on the group and controls when the field is disabled.
- Increment and decrement buttons are labeled for screen readers.
</page>

<page url="https://prototyper-ui.com/docs/components/popover" slug="components/popover">
# Popover
> A popup anchored to a trigger element built on Base UI
URL: https://prototyper-ui.com/docs/components/popover
Base UI reference: https://base-ui.com/react/components/popover
```tsx
import { Button } from "@/components/ui/button"
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover"
import { Switch } from "@/components/ui/switch"

export default function PopoverDemo() {
  return (
    <Popover>
      <PopoverTrigger render={<Button variant="outline" />}>
        Settings
      </PopoverTrigger>
      <PopoverContent>
        <div className="flex flex-col gap-4 p-4">
          <Switch defaultChecked>Wi-Fi</Switch>
          <Switch defaultChecked>Bluetooth</Switch>
          <Switch>Mute</Switch>
        </div>
      </PopoverContent>
    </Popover>
  )
}
```

## Installation

```bash
pnpm dlx shadcn@latest add https://prototyper-ui.com/r/popover.json
```

This will add the following files to your project:

- `components/ui/popover.tsx`

## Usage

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

<Popover>
  <PopoverTrigger>Open</PopoverTrigger>
  <PopoverContent>
    <p>Popover content here.</p>
  </PopoverContent>
</Popover>
```

## Anatomy

```tsx
<Popover>
  <PopoverTrigger />
  <PopoverContent>
    <PopoverHeader>
      <PopoverTitle />
      <PopoverDescription />
    </PopoverHeader>
    {/* your content */}
  </PopoverContent>
</Popover>
```

| Sub-component        | `data-slot`            | Purpose                                       | Required |
| -------------------- | ---------------------- | --------------------------------------------- | -------- |
| `Popover`            | `popover`              | Root provider, manages open/close state        | Yes      |
| `PopoverTrigger`     | `popover-trigger`      | Element that toggles the popover               | Yes      |
| `PopoverContent`     | `popover-content`      | The popup panel anchored to the trigger        | Yes      |
| `PopoverHeader`      | `popover-header`       | Flex container for title and description       | No       |
| `PopoverTitle`       | `popover-title`        | Accessible title for the popover               | No       |
| `PopoverDescription` | `popover-description`  | Accessible description for the popover         | No       |

## Examples

### Container Padding
```tsx
import { Button } from "@/components/ui/button"
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover"

export default function PopoverContainerPadding() {
  return (
    <Popover>
      <PopoverTrigger render={<Button variant="outline" />}>
        Container Padding
      </PopoverTrigger>
      <PopoverContent side="top" className="max-w-[150px]">
        <div className="p-4">This is a popover.</div>
      </PopoverContent>
    </Popover>
  )
}
```

### Cross Offset
```tsx
import { Button } from "@/components/ui/button"
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover"

export default function PopoverCrossOffset() {
  return (
    <Popover>
      <PopoverTrigger render={<Button variant="outline" />}>
        Cross offset
      </PopoverTrigger>
      <PopoverContent side="top" alignOffset={100}>
        <div className="p-4">Offset by an additional 100px.</div>
      </PopoverContent>
    </Popover>
  )
}
```

### Flipping
```tsx
import { Button } from "@/components/ui/button"
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover"

export default function PopoverFlipping() {
  return (
    <div className="flex gap-4">
      <Popover>
        <PopoverTrigger render={<Button variant="outline" />}>
          Default
        </PopoverTrigger>
        <PopoverContent side="bottom" className="max-w-[150px]">
          <div className="p-4">
            This is a popover that will flip if it can't fully render below
            the button.
          </div>
        </PopoverContent>
      </Popover>
      <Popover>
        <PopoverTrigger render={<Button variant="outline" />}>
          shouldFlip=false
        </PopoverTrigger>
        <PopoverContent side="bottom" className="max-w-[150px]">
          <div className="p-4">
            This is a popover that won't flip if it can't fully render below
            the button.
          </div>
        </PopoverContent>
      </Popover>
    </div>
  )
}
```

### Offset
```tsx
import { Button } from "@/components/ui/button"
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover"

export default function PopoverOffset() {
  return (
    <Popover>
      <PopoverTrigger render={<Button variant="outline" />}>
        Offset
      </PopoverTrigger>
      <PopoverContent sideOffset={50}>
        <div className="p-4">Offset by an additional 50px.</div>
      </PopoverContent>
    </Popover>
  )
}
```

### Position
```tsx
import { Button } from "@/components/ui/button"
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover"

export default function PopoverPosition() {
  return (
    <div className="flex gap-4">
      <Popover>
        <PopoverTrigger render={<Button variant="outline" size="icon" />}>
          ⬅️
        </PopoverTrigger>
        <PopoverContent side="left" className="max-w-[150px]">
          <div className="p-4">
            In left-to-right, this is on the left. In right-to-left, this is
            on the right.
          </div>
        </PopoverContent>
      </Popover>
      <Popover>
        <PopoverTrigger render={<Button variant="outline" size="icon" />}>
          ⬆️
        </PopoverTrigger>
        <PopoverContent side="top" className="max-w-[150px]">
          <div className="p-4">This popover is above the button.</div>
        </PopoverContent>
      </Popover>
      <Popover>
        <PopoverTrigger render={<Button variant="outline" size="icon" />}>
          ⬇️
        </PopoverTrigger>
        <PopoverContent side="bottom" className="max-w-[150px]">
          <div className="p-4">This popover is below the button.</div>
        </PopoverContent>
      </Popover>
      <Popover>
        <PopoverTrigger render={<Button variant="outline" size="icon" />}>
          ➡️
        </PopoverTrigger>
        <PopoverContent side="right" className="max-w-[150px]">
          <div className="p-4">
            In left-to-right, this is on the right. In right-to-left, this is
            on the left.
          </div>
        </PopoverContent>
      </Popover>
    </div>
  )
}
```

## Styling

### Data Slots

Use `data-slot` attributes to target specific parts of the popover:

| Slot name              | Element                          |
| ---------------------- | -------------------------------- |
| `popover`              | Root provider (no DOM rendered)  |
| `popover-trigger`      | The trigger element              |
| `popover-content`      | The popup panel                  |
| `popover-header`       | Header container                 |
| `popover-title`        | Title heading                    |
| `popover-description`  | Description text                 |

### Customization Examples

```css
/* Make popover wider */
[data-slot="popover-content"] {
  @apply min-w-[16rem];
}

/* Style the popover title */
[data-slot="popover-title"] {
  @apply text-base font-bold;
}
```

```tsx
{/* Override styles via className */}
<PopoverContent className="w-80 p-4">
  <PopoverHeader className="mb-4">
    <PopoverTitle>Settings</PopoverTitle>
  </PopoverHeader>
  {/* ... */}
</PopoverContent>
```

## API Reference

### Popover

Root component that manages open/close state.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | - | Controlled open state |
| `onOpenChange` | `(open: boolean) => void` | - | Callback when open state changes |
| `defaultOpen` | `boolean` | `false` | Initial open state for uncontrolled usage |

All [Base UI Popover.Root props](https://base-ui.com/react/components/popover) are forwarded via `...props`.

### PopoverTrigger

Element that toggles the popover when clicked.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Popover.Trigger props](https://base-ui.com/react/components/popover) are forwarded via `...props`.

### PopoverContent

The popup panel rendered inside a portal with a positioner.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"start" \| "center" \| "end"` | `"center"` | Alignment relative to the trigger |
| `alignOffset` | `number` | `0` | Offset from the alignment edge |
| `side` | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | Preferred side relative to trigger |
| `sideOffset` | `number` | `4` | Gap between trigger and popup |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Popover content |

All [Base UI Popover.Popup props](https://base-ui.com/react/components/popover) are forwarded via `...props`.

### PopoverHeader

Flex column container for title and description.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Header content |

Standard div props are forwarded via `...props`.

### PopoverTitle

Accessible title for the popover.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Popover.Title props](https://base-ui.com/react/components/popover) are forwarded via `...props`.

### PopoverDescription

Accessible description for the popover.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Popover.Description props](https://base-ui.com/react/components/popover) are forwarded via `...props`.

## Accessibility

### Keyboard Interactions

| Key         | Action                                                            |
| ----------- | ----------------------------------------------------------------- |
| `Escape`    | Closes the popover                                                |
| `Tab`       | Moves focus to the next focusable element within the popover      |
| `Shift+Tab` | Moves focus to the previous focusable element within the popover  |

### ARIA Attributes

- `PopoverContent` receives `role="dialog"` by default via Base UI.
- `aria-labelledby` is automatically linked to `PopoverTitle` when present.
- `aria-describedby` is automatically linked to `PopoverDescription` when present.
- Focus moves into the popover when it opens.
- Focus returns to the trigger element when the popover closes.
</page>

<page url="https://prototyper-ui.com/docs/components/progress" slug="components/progress">
# Progress
> A progress bar showing completion status
URL: https://prototyper-ui.com/docs/components/progress
Base UI reference: https://base-ui.com/react/components/progress
```tsx
"use client"

import React from "react"

import {
  Progress,
  ProgressLabel,
  ProgressValue,
} from "@/components/ui/progress"

export default function ProgressDemo() {
  const [progress, setProgress] = React.useState(13)

  React.useEffect(() => {
    const timer = setTimeout(() => setProgress(80), 500)
    return () => clearTimeout(timer)
  }, [])

  return (
    <Progress value={progress} className="w-3/5">
      <div className="flex w-full justify-between">
        <ProgressLabel>Loading...</ProgressLabel>
        <ProgressValue />
      </div>
    </Progress>
  )
}
```

## Installation

```bash
pnpm dlx shadcn@latest add https://prototyper-ui.com/r/progress.json
```

This will add the following files to your project:

- `components/ui/progress.tsx`

## Usage

```tsx
import { Progress, ProgressLabel } from "@/components/ui/progress"

<Progress value={50}>
  <ProgressLabel>Loading...</ProgressLabel>
</Progress>
```

## Anatomy

```tsx
<Progress>
  <ProgressLabel />
  <ProgressValue />
  {/* ProgressTrack and ProgressIndicator are rendered internally by Progress */}
</Progress>
```

| Sub-component       | `data-slot`          | Purpose                                    | Required |
| ------------------- | -------------------- | ------------------------------------------ | -------- |
| `Progress`          | `progress`           | Root provider with built-in track/indicator| Yes      |
| `ProgressTrack`     | `progress-track`     | Background track for the indicator         | Yes      |
| `ProgressIndicator` | `progress-indicator` | Filled portion representing progress       | Yes      |
| `ProgressLabel`     | `progress-label`     | Accessible label for the progress bar      | No       |
| `ProgressValue`     | `progress-value`     | Displays the current value as text         | No       |

> **Note:** `ProgressTrack` and `ProgressIndicator` are rendered automatically inside the `Progress` component. You do not need to include them manually.

## Examples

### Custom Format
```tsx
import {
  Progress,
  ProgressLabel,
} from "@/components/ui/progress"

export default function ProgressCustomFormat() {
  return (
    <Progress value={30} className="w-3/5">
      <div className="flex w-full justify-between">
        <ProgressLabel>Feeding...</ProgressLabel>
        <span className="text-sm text-muted-foreground">30 of 100 dogs</span>
      </div>
    </Progress>
  )
}
```

### Reusable
```tsx
import {
  Progress,
  ProgressLabel,
  ProgressValue,
} from "@/components/ui/progress"

export default function ProgressReusable() {
  return (
    <Progress value={80} className="w-3/5">
      <div className="flex w-full justify-between">
        <ProgressLabel>Loading...</ProgressLabel>
        <ProgressValue />
      </div>
    </Progress>
  )
}
```

### Value Format
```tsx
import {
  Progress,
  ProgressLabel,
  ProgressValue,
} from "@/components/ui/progress"

export default function ProgressValueFormat() {
  return (
    <Progress value={60} className="w-3/5">
      <div className="flex w-full justify-between">
        <ProgressLabel>Sending...</ProgressLabel>
        <ProgressValue />
      </div>
    </Progress>
  )
}
```

## Styling

### Data Slots

Use `data-slot` attributes to target specific parts of the progress bar:

| Slot name            | Element                              |
| -------------------- | ------------------------------------ |
| `progress`           | Root wrapper                         |
| `progress-track`     | Background track bar                 |
| `progress-indicator` | Filled indicator bar                 |
| `progress-label`     | Label text                           |
| `progress-value`     | Value text                           |

### Customization Examples

```css
/* Make the progress track taller */
[data-slot="progress-track"] {
  @apply h-4 rounded-lg;
}

/* Custom indicator with gradient */
[data-slot="progress-indicator"] {
  @apply bg-gradient-to-r from-green-500 to-emerald-500;
}
```

```tsx
{/* Override color via the color prop */}
<Progress value={75} color="success">
  <ProgressLabel>Upload</ProgressLabel>
</Progress>
```

## API Reference

### Progress

Root component that provides progress value context and renders the track and indicator internally.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number \| null` | - | Current progress value, null for indeterminate |
| `min` | `number` | `0` | Minimum value |
| `max` | `number` | `100` | Maximum value |
| `color` | `"default" \| "success" \| "warning" \| "destructive"` | `"default"` | Color variant for the track and indicator |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Progress content (label, value) |

All [Base UI Progress.Root props](https://base-ui.com/react/components/progress) are forwarded via `...props`.

### ProgressTrack

Background track that contains the indicator. Rendered automatically by `Progress`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `color` | `"default" \| "success" \| "warning" \| "destructive"` | `"default"` | Color variant for the track |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Track content (typically ProgressIndicator) |

All [Base UI Progress.Track props](https://base-ui.com/react/components/progress) are forwarded via `...props`.

### ProgressIndicator

The filled portion of the track representing current progress. Rendered automatically by `Progress`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `color` | `"default" \| "success" \| "warning" \| "destructive"` | `"default"` | Color variant for the indicator |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Progress.Indicator props](https://base-ui.com/react/components/progress) are forwarded via `...props`.

### ProgressLabel

Accessible label for the progress bar.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Label text |

All [Base UI Progress.Label props](https://base-ui.com/react/components/progress) are forwarded via `...props`.

### ProgressValue

Displays the current progress value as formatted text.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Custom value rendering |

All [Base UI Progress.Value props](https://base-ui.com/react/components/progress) are forwarded via `...props`.

### progressTrackVariants

A `cva` helper exported for applying progress track styles outside of the `<ProgressTrack>` component.

```tsx
import { progressTrackVariants } from "@/components/ui/progress"

<div className={progressTrackVariants({ color: "success" })}>Custom track</div>
```

### progressIndicatorVariants

A `cva` helper exported for applying progress indicator styles outside of the `<ProgressIndicator>` component.

```tsx
import { progressIndicatorVariants } from "@/components/ui/progress"

<div className={progressIndicatorVariants({ color: "warning" })}>Custom indicator</div>
```

## Accessibility

### Keyboard Interactions

The progress bar is a non-interactive display element and does not have keyboard interactions. Focus management is handled by surrounding interactive elements.

### ARIA Attributes

- The progress bar renders with `role="progressbar"` via the Base UI primitive.
- `aria-valuenow` reflects the current value.
- `aria-valuemin` and `aria-valuemax` define the range.
- When `value` is `null`, the progress bar enters indeterminate mode and `aria-valuenow` is removed.
- `aria-labelledby` is automatically linked to `ProgressLabel` when present.
- The `data-indeterminate` attribute is set when value is `null`, and `data-complete` is set when value equals max.
- Screen readers announce the progress value and its label.
</page>

<page url="https://prototyper-ui.com/docs/components/radio-group" slug="components/radio-group">
# Radio Group
> A group of radio buttons built on Base UI
URL: https://prototyper-ui.com/docs/components/radio-group
Base UI reference: https://base-ui.com/react/components/radio
```tsx
import { FieldLabel } from "@/components/ui/field"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"

export default function RadioGroupDemo() {
  return (
    <RadioGroup>
      <FieldLabel>Favorite pet</FieldLabel>
      <label className="flex items-center gap-2">
        <RadioGroupItem value="dogs" />
        Dog
      </label>
      <label className="flex items-center gap-2">
        <RadioGroupItem value="cats" />
        Cat
      </label>
      <label className="flex items-center gap-2">
        <RadioGroupItem value="dragon" />
        Dragon
      </label>
    </RadioGroup>
  )
}
```

## Installation

```bash
pnpm dlx shadcn@latest add https://prototyper-ui.com/r/radio-group.json
```

This will add the following files to your project:

- `components/ui/radio-group.tsx`

## Usage

```tsx
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"

<RadioGroup>
  <RadioGroupItem value="option-1">Option 1</RadioGroupItem>
  <RadioGroupItem value="option-2">Option 2</RadioGroupItem>
  <RadioGroupItem value="option-3">Option 3</RadioGroupItem>
</RadioGroup>
```

## Anatomy

```tsx
<RadioGroup>
  <RadioGroupItem />
  <RadioGroupItem />
  <RadioGroupItem />
</RadioGroup>
```

| Sub-component    | `data-slot`            | Purpose                                     | Required |
| ---------------- | ---------------------- | ------------------------------------------- | -------- |
| `RadioGroup`     | `radio-group`          | Root container, manages selection state     | Yes      |
| `RadioGroupItem` | `radio-group-item`     | Individual radio button with built-in indicator | Yes  |
| (indicator)      | `radio-group-indicator`| Selection dot (rendered internally by RadioGroupItem) | Yes |

## Examples

### Description
```tsx
import { FieldLabel } from "@/components/ui/field"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"

export default function RadioGroupDescription() {
  return (
    <RadioGroup>
      <FieldLabel>Favorite avatar</FieldLabel>
      <label className="flex items-center gap-2">
        <RadioGroupItem value="wizard" />
        Wizard
      </label>
      <label className="flex items-center gap-2">
        <RadioGroupItem value="dragon" />
        Dragon
      </label>
      <p className="text-sm text-muted-foreground">
        Please select an avatar.
      </p>
    </RadioGroup>
  )
}
```

### Disabled
```tsx
import { FieldLabel } from "@/components/ui/field"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"

export default function RadioGroupDisabled() {
  return (
    <RadioGroup disabled>
      <FieldLabel>Favorite sport</FieldLabel>
      <label className="flex items-center gap-2">
        <RadioGroupItem value="soccer" />
        Soccer
      </label>
      <label className="flex items-center gap-2">
        <RadioGroupItem value="baseball" />
        Baseball
      </label>
      <label className="flex items-center gap-2">
        <RadioGroupItem value="basketball" />
        Basketball
      </label>
    </RadioGroup>
  )
}
```

### Disabled Individual
```tsx
import { FieldLabel } from "@/components/ui/field"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"

export default function RadioGroupDisabledIndividual() {
  return (
    <RadioGroup>
      <FieldLabel>Favorite sport</FieldLabel>
      <label className="flex items-center gap-2">
        <RadioGroupItem value="soccer" />
        Soccer
      </label>
      <label className="flex items-center gap-2 opacity-50">
        <RadioGroupItem value="baseball" disabled />
        Baseball
      </label>
      <label className="flex items-center gap-2">
        <RadioGroupItem value="basketball" />
        Basketball
      </label>
    </RadioGroup>
  )
}
```

### Orientation
```tsx
import { FieldLabel } from "@/components/ui/field"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"

export default function RadioGroupOrientation() {
  return (
    <RadioGroup className="flex flex-row gap-4">
      <FieldLabel>Favorite avatar</FieldLabel>
      <label className="flex items-center gap-2">
        <RadioGroupItem value="wizard" />
        Wizard
      </label>
      <label className="flex items-center gap-2">
        <RadioGroupItem value="dragon" />
        Dragon
      </label>
    </RadioGroup>
  )
}
```

### Read Only
```tsx
import { FieldLabel } from "@/components/ui/field"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"

export default function RadioGroupReadonly() {
  return (
    <RadioGroup defaultValue="wizard" readOnly>
      <FieldLabel>Favorite avatar</FieldLabel>
      <label className="flex items-center gap-2">
        <RadioGroupItem value="wizard" />
        Wizard
      </label>
      <label className="flex items-center gap-2">
        <RadioGroupItem value="dragon" />
        Dragon
      </label>
    </RadioGroup>
  )
}
```

### Reusable
```tsx
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
import { FieldLabel } from "@/components/ui/field"

export default function RadioGroupReusable() {
  return (
    <RadioGroup>
      <FieldLabel>
        Favorite sport <span className="text-destructive">*</span>
      </FieldLabel>
      <label className="flex items-center gap-2">
        <RadioGroupItem value="soccer" />
        Soccer
      </label>
      <label className="flex items-center gap-2">
        <RadioGroupItem value="baseball" />
        Baseball
      </label>
      <label className="flex items-center gap-2">
        <RadioGroupItem value="basketball" />
        Basketball
      </label>
      <p className="text-sm text-muted-foreground">Select a favorite sport</p>
    </RadioGroup>
  )
}
```

### Validation
```tsx
import { Button } from "@/components/ui/button"
import { FieldError, FieldLabel } from "@/components/ui/field"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"

export default function RadioGroupValidation() {
  return (
    <form className="flex flex-col gap-2">
      <RadioGroup className="group" name="pet" required>
        <FieldLabel>Favorite pet</FieldLabel>
        <label className="flex items-center gap-2">
          <RadioGroupItem value="dogs" />
          Dog
        </label>
        <label className="flex items-center gap-2">
          <RadioGroupItem value="cats" />
          Cat
        </label>
        <label className="flex items-center gap-2">
          <RadioGroupItem value="dragon" />
          Dragon
        </label>
        <FieldError />
      </RadioGroup>
      <Button className="w-fit" type="submit">
        Submit
      </Button>
    </form>
  )
}
```

## Styling

### Data Slots

Use `data-slot` attributes to target specific parts of the radio group:

| Slot name              | Element                                |
| ---------------------- | -------------------------------------- |
| `radio-group`          | Root container for all radio items     |
| `radio-group-item`     | Individual radio button circle         |
| `radio-group-indicator`| The selection dot inside the circle    |

### Customization Examples

```css
/* Make radio items larger */
[data-slot="radio-group-item"] {
  @apply size-5;
}

/* Custom checked color */
[data-slot="radio-group-item"] {
  @apply data-checked:bg-green-600 data-checked:border-green-600;
}
```

```tsx
{/* Override layout via className */}
<RadioGroup className="flex flex-row gap-4">
  <RadioGroupItem value="a">A</RadioGroupItem>
  <RadioGroupItem value="b">B</RadioGroupItem>
</RadioGroup>
```

## API Reference

### RadioGroup

Root container that manages which radio item is selected.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | - | Controlled selected value |
| `defaultValue` | `string` | - | Initial selected value for uncontrolled usage |
| `onValueChange` | `(value: string, event: Event) => void` | - | Callback when selection changes |
| `disabled` | `boolean` | `false` | Whether all radio items are disabled |
| `readOnly` | `boolean` | `false` | Whether the group is read-only |
| `required` | `boolean` | `false` | Whether a selection is required |
| `name` | `string` | - | Name attribute for form submission |
| `orientation` | `"horizontal" \| "vertical"` | `"vertical"` | Orientation of the radio group |
| `className` | `string` | - | Additional CSS classes |

All [Base UI RadioGroup props](https://base-ui.com/react/components/radio) are forwarded via `...props`.

### RadioGroupItem

An individual radio button with a built-in selection indicator.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | - | Unique value for this radio item (required) |
| `disabled` | `boolean` | `false` | Whether this individual item is disabled |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Radio props](https://base-ui.com/react/components/radio) are forwarded via `...props`.

## Accessibility

### Keyboard Interactions

| Key          | Action                                              |
| ------------ | --------------------------------------------------- |
| `ArrowDown`  | Moves focus and selection to the next radio item    |
| `ArrowRight` | Moves focus and selection to the next radio item    |
| `ArrowUp`    | Moves focus and selection to the previous radio item|
| `ArrowLeft`  | Moves focus and selection to the previous radio item|
| `Tab`        | Moves focus into / out of the radio group           |

### ARIA Attributes

- `RadioGroup` renders with `role="radiogroup"` via Base UI.
- Each `RadioGroupItem` renders with `role="radio"`.
- `aria-checked` is set to `true` on the selected item and `false` on others.
- `aria-disabled` is set when the group or an individual item is disabled.
- `aria-readonly` is set when the group is read-only.
- `aria-required` is set when the group is required.
- Screen readers announce each radio item label and its selected/unselected state.
</page>

<page url="https://prototyper-ui.com/docs/components/select" slug="components/select">
# Select
> A dropdown select input built on Base UI
URL: https://prototyper-ui.com/docs/components/select
Base UI reference: https://base-ui.com/react/components/select
```tsx
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@/components/ui/select"

export default function SelectDemo() {
  return (
    <Select defaultValue="apple">
      <SelectTrigger className="w-[180px]">
        <SelectValue />
      </SelectTrigger>
      <SelectContent>
        <SelectItem value="apple">Apple</SelectItem>
        <SelectItem value="banana">Banana</SelectItem>
        <SelectItem value="blueberry">Blueberry</SelectItem>
        <SelectItem value="grapes">Grapes</SelectItem>
        <SelectItem value="pineapple">Pineapple</SelectItem>
      </SelectContent>
    </Select>
  )
}
```

## Installation

```bash
pnpm dlx shadcn@latest add https://prototyper-ui.com/r/select.json
```

This will add the following files to your project:

- `components/ui/select.tsx`

## Usage

```tsx
import {
  Select,
  SelectTrigger,
  SelectValue,
  SelectContent,
  SelectItem,
} from "@/components/ui/select"

<Select>
  <SelectTrigger>
    <SelectValue placeholder="Select an option" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="option-1">Option 1</SelectItem>
    <SelectItem value="option-2">Option 2</SelectItem>
  </SelectContent>
</Select>
```

## Anatomy

```tsx
<Select>
  <SelectTrigger>
    <SelectValue />
  </SelectTrigger>
  <SelectContent>
    <SelectGroup>
      <SelectLabel />
      <SelectItem />
    </SelectGroup>
    <SelectSeparator />
  </SelectContent>
</Select>
```

| Sub-component          | `data-slot`                  | Purpose                                        | Required |
| ---------------------- | ---------------------------- | ---------------------------------------------- | -------- |
| `Select`               | `select`                     | Root provider, manages selection state         | Yes      |
| `SelectTrigger`        | `select-trigger`             | Button that opens the dropdown                 | Yes      |
| `SelectValue`          | `select-value`               | Displays the currently selected value          | Yes      |
| `SelectContent`        | `select-content`             | Popup container for items                      | Yes      |
| `SelectItem`           | `select-item`                | An individual selectable option                | Yes      |
| `SelectGroup`          | `select-group`               | Groups related items together                  | No       |
| `SelectLabel`          | `select-label`               | Label for a group of items                     | No       |
| `SelectSeparator`      | `select-separator`           | Visual divider between items or groups         | No       |
| `SelectScrollUpButton` | `select-scroll-up-button`    | Scroll indicator at the top of the list        | No       |
| `SelectScrollDownButton` | `select-scroll-down-button` | Scroll indicator at the bottom of the list    | No       |

## Examples

### Content
```tsx
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@/components/ui/select"

export default function SelectContentDemo() {
  const options = [
    { id: 1, name: "Aerospace" },
    { id: 2, name: "Mechanical" },
    { id: 3, name: "Civil" },
    { id: 4, name: "Biomedical" },
    { id: 5, name: "Nuclear" },
    { id: 6, name: "Industrial" },
    { id: 7, name: "Chemical" },
    { id: 8, name: "Agricultural" },
    { id: 9, name: "Electrical" },
  ]

  return (
    <Select defaultValue="1">
      <SelectTrigger className="w-[200px]">
        <SelectValue />
      </SelectTrigger>
      <SelectContent>
        {options.map((item) => (
          <SelectItem key={item.id} value={item.id.toString()}>
            {item.name}
          </SelectItem>
        ))}
      </SelectContent>
    </Select>
  )
}
```

### Description
```tsx
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@/components/ui/select"

export default function SelectDescription() {
  return (
    <div className="flex flex-col gap-2">
      <Select>
        <SelectTrigger className="w-[200px]">
          <SelectValue />
        </SelectTrigger>
        <SelectContent>
          <SelectItem value="aardvark">Aardvark</SelectItem>
          <SelectItem value="cat">Cat</SelectItem>
          <SelectItem value="dog">Dog</SelectItem>
          <SelectItem value="kangaroo">Kangaroo</SelectItem>
          <SelectItem value="panda">Panda</SelectItem>
          <SelectItem value="snake">Snake</SelectItem>
        </SelectContent>
      </Select>
      <p className="text-sm text-muted-foreground">
        Please select an animal.
      </p>
    </div>
  )
}
```

### Disabled
```tsx
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@/components/ui/select"

export default function SelectDisabled() {
  return (
    <Select disabled>
      <SelectTrigger className="w-[180px]">
        <SelectValue />
      </SelectTrigger>
      <SelectContent>
        <SelectItem value="apple">Apple</SelectItem>
        <SelectItem value="banana">Banana</SelectItem>
        <SelectItem value="blueberry">Blueberry</SelectItem>
      </SelectContent>
    </Select>
  )
}
```

### Disabled Items
```tsx
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@/components/ui/select"

export default function SelectDisabledItems() {
  return (
    <Select defaultValue="apple">
      <SelectTrigger className="w-[180px]">
        <SelectValue />
      </SelectTrigger>
      <SelectContent>
        <SelectItem value="apple">Apple</SelectItem>
        <SelectItem value="banana" disabled>
          Banana (out of stock)
        </SelectItem>
        <SelectItem value="blueberry">Blueberry</SelectItem>
        <SelectItem value="grapes" disabled>
          Grapes (out of stock)
        </SelectItem>
        <SelectItem value="pineapple">Pineapple</SelectItem>
      </SelectContent>
    </Select>
  )
}
```

### Links
```tsx
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@/components/ui/select"

export default function SelectLinks() {
  return (
    <Select>
      <SelectTrigger className="w-[200px]">
        <SelectValue />
      </SelectTrigger>
      <SelectContent>
        <SelectItem value="create-new">Create new…</SelectItem>
        <SelectItem value="proposal">Proposal</SelectItem>
        <SelectItem value="budget">Budget</SelectItem>
        <SelectItem value="onboarding">Onboarding</SelectItem>
      </SelectContent>
    </Select>
  )
}
```

### Reusable
```tsx
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@/components/ui/select"

export default function SelectReusable() {
  return (
    <div className="flex flex-col gap-2">
      <label className="text-sm font-medium">Ice cream flavor</label>
      <Select>
        <SelectTrigger className="w-[200px]">
          <SelectValue />
        </SelectTrigger>
        <SelectContent>
          <SelectItem value="chocolate">Chocolate</SelectItem>
          <SelectItem value="mint">Mint</SelectItem>
          <SelectItem value="strawberry">Strawberry</SelectItem>
          <SelectItem value="vanilla">Vanilla</SelectItem>
        </SelectContent>
      </Select>
      <p className="text-sm text-muted-foreground">Select a flavor</p>
    </div>
  )
}
```

### Sections
```tsx
import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectLabel,
  SelectSeparator,
  SelectTrigger,
  SelectValue,
} from "@/components/ui/select"

export default function SelectSections() {
  return (
    <Select defaultValue="apple">
      <SelectTrigger className="w-[180px]">
        <SelectValue />
      </SelectTrigger>
      <SelectContent>
        <SelectGroup>
          <SelectLabel>Fruits</SelectLabel>
          <SelectItem value="apple">Apple</SelectItem>
          <SelectItem value="banana">Banana</SelectItem>
          <SelectItem value="blueberry">Blueberry</SelectItem>
        </SelectGroup>
        <SelectSeparator />
        <SelectGroup>
          <SelectLabel>Vegetables</SelectLabel>
          <SelectItem value="carrot">Carrot</SelectItem>
          <SelectItem value="potato">Potato</SelectItem>
          <SelectItem value="tomato">Tomato</SelectItem>
        </SelectGroup>
      </SelectContent>
    </Select>
  )
}
```

### Sections Dynamic
```tsx
import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectLabel,
  SelectTrigger,
  SelectValue,
} from "@/components/ui/select"

export default function SelectSectionsDynamic() {
  const options = [
    {
      name: "Fruit",
      children: [
        { name: "Apple" },
        { name: "Banana" },
        { name: "Orange" },
        { name: "Honeydew" },
        { name: "Grapes" },
        { name: "Watermelon" },
        { name: "Cantaloupe" },
        { name: "Pear" },
      ],
    },
    {
      name: "Vegetable",
      children: [
        { name: "Cabbage" },
        { name: "Broccoli" },
        { name: "Carrots" },
        { name: "Lettuce" },
        { name: "Spinach" },
        { name: "Bok Choy" },
        { name: "Cauliflower" },
        { name: "Potatoes" },
      ],
    },
  ]

  return (
    <Select>
      <SelectTrigger className="w-[200px]">
        <SelectValue />
      </SelectTrigger>
      <SelectContent>
        {options.map((section) => (
          <SelectGroup key={section.name}>
            <SelectLabel>{section.name}</SelectLabel>
            {section.children.map((item) => (
              <SelectItem key={item.name} value={item.name.toLowerCase()}>
                {item.name}
              </SelectItem>
            ))}
          </SelectGroup>
        ))}
      </SelectContent>
    </Select>
  )
}
```

### Text Slots
```tsx
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@/components/ui/select"

export default function SelectTextSlots() {
  return (
    <Select>
      <SelectTrigger className="w-[200px]">
        <SelectValue />
      </SelectTrigger>
      <SelectContent>
        <SelectItem value="read" className="flex flex-col items-start">
          <span className="font-medium">Read only</span>
          <span className="text-sm text-muted-foreground">
            Read only
          </span>
        </SelectItem>
        <SelectItem value="write" className="flex flex-col items-start">
          <span className="font-medium">Write</span>
          <span className="text-sm text-muted-foreground">
            Read and write only
          </span>
        </SelectItem>
        <SelectItem value="admin" className="flex flex-col items-start">
          <span className="font-medium">Admin</span>
          <span className="text-sm text-muted-foreground">
            Full access
          </span>
        </SelectItem>
      </SelectContent>
    </Select>
  )
}
```

### Validation
```tsx
"use client"

import { useState } from "react"

import { Button } from "@/components/ui/button"
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@/components/ui/select"

export default function SelectValidation() {
  const [value, setValue] = useState<string | null>(null)
  const [error, setError] = useState<string>()

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault()
    if (!value) {
      setError("Please select an animal")
    } else {
      setError(undefined)
      alert(`Selected: ${value}`)
    }
  }

  return (
    <form onSubmit={handleSubmit} className="flex flex-col gap-4">
      <div className="flex flex-col gap-2">
        <Select value={value} onValueChange={(v) => {
          setValue(v)
          setError(undefined)
        }}>
          <SelectTrigger className="w-[200px]">
            <SelectValue />
          </SelectTrigger>
          <SelectContent>
            <SelectItem value="aardvark">Aardvark</SelectItem>
            <SelectItem value="cat">Cat</SelectItem>
            <SelectItem value="dog">Dog</SelectItem>
            <SelectItem value="kangaroo">Kangaroo</SelectItem>
            <SelectItem value="panda">Panda</SelectItem>
            <SelectItem value="snake">Snake</SelectItem>
          </SelectContent>
        </Select>
        {error && <p className="text-sm text-destructive">{error}</p>}
      </div>
      <Button className="w-fit" type="submit">
        Submit
      </Button>
    </form>
  )
}
```

## Styling

### Data Slots

Use `data-slot` attributes to target specific parts of the select:

| Slot name                  | Element                                  |
| -------------------------- | ---------------------------------------- |
| `select`                   | Root provider                            |
| `select-trigger`           | The trigger button                       |
| `select-value`             | Displayed selected value text            |
| `select-content`           | The dropdown popup panel                 |
| `select-item`              | An individual option                     |
| `select-group`             | Group wrapper for related items          |
| `select-label`             | Label for a group                        |
| `select-separator`         | Visual divider                           |
| `select-scroll-up-button`  | Top scroll indicator                     |
| `select-scroll-down-button`| Bottom scroll indicator                  |

### Customization Examples

```css
/* Make the trigger wider */
[data-slot="select-trigger"] {
  @apply w-64;
}

/* Custom highlight color for items */
[data-slot="select-item"][data-highlighted] {
  @apply bg-primary text-primary-foreground;
}
```

```tsx
{/* Override trigger size via className */}
<SelectTrigger className="w-80">
  <SelectValue placeholder="Choose..." />
</SelectTrigger>
```

## API Reference

### Select

Root component that manages selection state and context.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `any` | - | Initial value for uncontrolled usage |
| `value` | `any` | - | Controlled selected value |
| `onValueChange` | `(value: any) => void` | - | Callback when the selected value changes |
| `disabled` | `boolean` | `false` | Whether the select is disabled |

All [Base UI Select.Root props](https://base-ui.com/react/components/select) are forwarded via `...props`.

### SelectTrigger

Button that opens the dropdown when clicked.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"default" \| "sm" \| "lg"` | `"default"` | Size of the trigger |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Trigger content |

All [Base UI Select.Trigger props](https://base-ui.com/react/components/select) are forwarded via `...props`.

### SelectValue

Displays the currently selected value or a placeholder.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `placeholder` | `string` | - | Text shown when no value is selected |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Select.Value props](https://base-ui.com/react/components/select) are forwarded via `...props`.

### SelectContent

The dropdown popup panel rendered inside a portal with positioning.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | Preferred side of the trigger to render |
| `sideOffset` | `number` | `4` | Distance from the trigger in pixels |
| `align` | `"start" \| "center" \| "end"` | `"center"` | Alignment relative to the trigger |
| `alignOffset` | `number` | `0` | Offset from the alignment edge in pixels |
| `alignItemWithTrigger` | `boolean` | `true` | Align the selected item with the trigger |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Dropdown content |

All [Base UI Select.Popup props](https://base-ui.com/react/components/select) are forwarded via `...props`.

### SelectItem

An individual selectable option within the dropdown.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `any` | - | The value of this item |
| `disabled` | `boolean` | `false` | Whether the item is disabled |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Item label content |

All [Base UI Select.Item props](https://base-ui.com/react/components/select) are forwarded via `...props`.

### SelectGroup

Groups related items together with optional label.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Group content |

All [Base UI Select.Group props](https://base-ui.com/react/components/select) are forwarded via `...props`.

### SelectLabel

Label for a group of items.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Select.GroupLabel props](https://base-ui.com/react/components/select) are forwarded via `...props`.

### SelectSeparator

Visual divider between items or groups.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Select.Separator props](https://base-ui.com/react/components/select) are forwarded via `...props`.

### SelectScrollUpButton

Scroll indicator at the top of the dropdown list.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Select.ScrollUpArrow props](https://base-ui.com/react/components/select) are forwarded via `...props`.

### SelectScrollDownButton

Scroll indicator at the bottom of the dropdown list.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Select.ScrollDownArrow props](https://base-ui.com/react/components/select) are forwarded via `...props`.

### selectTriggerVariants

A `cva` helper exported for use outside of the `<SelectTrigger>` component (e.g., applying select trigger styles to custom elements).

```tsx
import { selectTriggerVariants } from "@/components/ui/select"

<div className={selectTriggerVariants({ size: "sm" })}>Custom trigger</div>
```

## Accessibility

### Keyboard Interactions

| Key              | Action                                                    |
| ---------------- | --------------------------------------------------------- |
| `Space`          | Opens the dropdown or selects the highlighted item        |
| `Enter`          | Opens the dropdown or selects the highlighted item        |
| `ArrowDown`      | Opens the dropdown or moves highlight to the next item    |
| `ArrowUp`        | Opens the dropdown or moves highlight to the previous item|
| `Home`           | Moves highlight to the first item                         |
| `End`            | Moves highlight to the last item                          |
| `Escape`         | Closes the dropdown                                       |
| `Tab`            | Closes the dropdown and moves focus to the next element   |

### ARIA Attributes

- The trigger renders with `role="combobox"` and `aria-haspopup="listbox"`.
- `aria-expanded` is set to `true` when the dropdown is open.
- The popup receives `role="listbox"`.
- Each item receives `role="option"` with `aria-selected` indicating the current selection.
- `aria-disabled` is set on disabled items.
- Screen readers announce the currently selected value from the trigger.
</page>

<page url="https://prototyper-ui.com/docs/components/slider" slug="components/slider">
# Slider
> A slider input for selecting values within a range
URL: https://prototyper-ui.com/docs/components/slider
Base UI reference: https://base-ui.com/react/components/slider
```tsx
import { FieldLabel } from "@/components/ui/field"
import {
  Slider,
  SliderControl,
  SliderIndicator,
  SliderOutput,
  SliderThumb,
  SliderTrack,
} from "@/components/ui/slider"

export default function SliderDemo() {
  return (
    <Slider defaultValue={[30]} className="w-3/5">
      <FieldLabel>Opacity</FieldLabel>
      <SliderOutput />
      <SliderControl>
        <SliderTrack>
          <SliderIndicator />
          <SliderThumb />
        </SliderTrack>
      </SliderControl>
    </Slider>
  )
}
```

## Installation

```bash
pnpm dlx shadcn@latest add https://prototyper-ui.com/r/slider.json
```

This will add the following files to your project:

- `components/ui/slider.tsx`

## Usage

```tsx
import {
  Slider,
  SliderControl,
  SliderTrack,
  SliderIndicator,
  SliderThumb,
} from "@/components/ui/slider"

<Slider defaultValue={50}>
  <SliderControl>
    <SliderTrack>
      <SliderIndicator />
      <SliderThumb />
    </SliderTrack>
  </SliderControl>
</Slider>
```

## Anatomy

```tsx
<Slider>
  <SliderOutput />
  <SliderControl>
    <SliderTrack>
      <SliderIndicator />
      <SliderThumb />
    </SliderTrack>
  </SliderControl>
</Slider>
```

| Sub-component    | `data-slot`        | Purpose                                     | Required |
| ---------------- | ------------------ | ------------------------------------------- | -------- |
| `Slider`         | `slider`           | Root provider, manages value state          | Yes      |
| `SliderControl`  | `slider-control`   | Touch/pointer interaction area              | Yes      |
| `SliderTrack`    | `slider-track`     | The visible track bar                       | Yes      |
| `SliderIndicator`| `slider-indicator` | Filled portion of the track                 | Yes      |
| `SliderThumb`    | `slider-thumb`     | Draggable thumb handle                      | Yes      |
| `SliderOutput`   | `slider-output`    | Displays the current value                  | No       |

## Examples

### Disabled
```tsx
import { FieldLabel } from "@/components/ui/field"
import {
  Slider,
  SliderControl,
  SliderIndicator,
  SliderThumb,
  SliderTrack,
} from "@/components/ui/slider"

export default function SliderDisabled() {
  return (
    <Slider defaultValue={[25]} disabled className="w-3/5">
      <FieldLabel>Cookies to share</FieldLabel>
      <SliderControl>
        <SliderTrack>
          <SliderIndicator />
          <SliderThumb />
        </SliderTrack>
      </SliderControl>
    </Slider>
  )
}
```

### Step Values
```tsx
import { FieldLabel } from "@/components/ui/field"
import {
  Slider,
  SliderControl,
  SliderIndicator,
  SliderThumb,
  SliderTrack,
} from "@/components/ui/slider"

export default function SliderStepValues() {
  return (
    <Slider min={0} max={100} step={5} className="w-3/5">
      <FieldLabel>Amount</FieldLabel>
      <SliderControl>
        <SliderTrack>
          <SliderIndicator />
          <SliderThumb />
        </SliderTrack>
      </SliderControl>
    </Slider>
  )
}
```

### Values
```tsx
import { FieldLabel } from "@/components/ui/field"
import {
  Slider,
  SliderControl,
  SliderIndicator,
  SliderOutput,
  SliderThumb,
  SliderTrack,
} from "@/components/ui/slider"

export default function SliderValues() {
  return (
    <Slider min={50} max={150} defaultValue={[100]} className="w-3/5">
      <FieldLabel>Cookies to Buy</FieldLabel>
      <SliderOutput />
      <SliderControl>
        <SliderTrack>
          <SliderIndicator />
          <SliderThumb />
        </SliderTrack>
      </SliderControl>
    </Slider>
  )
}
```

### Vertical
```tsx
import {
  Slider,
  SliderControl,
  SliderIndicator,
  SliderThumb,
  SliderTrack,
} from "@/components/ui/slider"

export default function SliderVertical() {
  return (
    <Slider
      orientation="vertical"
      aria-label="Opacity"
      max={1}
      step={0.01}
      className="h-[150px]"
    >
      <SliderControl>
        <SliderTrack>
          <SliderIndicator />
          <SliderThumb />
        </SliderTrack>
      </SliderControl>
    </Slider>
  )
}
```

## Styling

### Data Slots

Use `data-slot` attributes to target specific parts of the slider:

| Slot name          | Element                          |
| ------------------ | -------------------------------- |
| `slider`           | Root wrapper                     |
| `slider-control`   | Touch/pointer interaction area   |
| `slider-track`     | The visible track bar            |
| `slider-indicator` | Filled portion of the track      |
| `slider-thumb`     | Draggable thumb handle           |
| `slider-output`    | Current value display            |

### Customization Examples

```css
/* Custom track height */
[data-slot="slider-track"] {
  @apply h-3 rounded-lg;
}

/* Custom indicator color */
[data-slot="slider-indicator"] {
  @apply bg-green-600;
}
```

```tsx
{/* Override styles via className */}
<Slider className="w-64" defaultValue={50}>
  <SliderControl>
    <SliderTrack className="h-3">
      <SliderIndicator />
      <SliderThumb />
    </SliderTrack>
  </SliderControl>
</Slider>
```

## API Reference

### Slider

Root component that manages value state and layout.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number \| number[]` | - | Controlled value |
| `defaultValue` | `number \| number[]` | - | Initial value for uncontrolled usage |
| `onValueChange` | `(value: number \| number[], event: Event) => void` | - | Callback when value changes |
| `onValueCommitted` | `(value: number \| number[], event: Event) => void` | - | Callback when interaction ends (e.g. pointer up) |
| `min` | `number` | `0` | Minimum value |
| `max` | `number` | `100` | Maximum value |
| `step` | `number` | `1` | Step increment |
| `largeStep` | `number` | `10` | Step increment for Page Up / Page Down |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Orientation of the slider |
| `disabled` | `boolean` | `false` | Whether the slider is disabled |
| `name` | `string` | - | Name attribute for form submission |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Slider props](https://base-ui.com/react/components/slider) are forwarded via `...props`.

### SliderControl

The area that receives touch and pointer events for dragging.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Slider.Control props](https://base-ui.com/react/components/slider) are forwarded via `...props`.

### SliderTrack

The visible bar that represents the full range.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Slider.Track props](https://base-ui.com/react/components/slider) are forwarded via `...props`.

### SliderIndicator

The filled portion of the track that shows the current value.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Slider.Indicator props](https://base-ui.com/react/components/slider) are forwarded via `...props`.

### SliderThumb

The draggable handle that the user interacts with.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Slider.Thumb props](https://base-ui.com/react/components/slider) are forwarded via `...props`.

### SliderOutput

Displays the current slider value as text.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Slider.Value props](https://base-ui.com/react/components/slider) are forwarded via `...props`.

## Accessibility

### Keyboard Interactions

| Key          | Action                                         |
| ------------ | ---------------------------------------------- |
| `ArrowRight` | Increases the value by one step                |
| `ArrowUp`    | Increases the value by one step                |
| `ArrowLeft`  | Decreases the value by one step                |
| `ArrowDown`  | Decreases the value by one step                |
| `PageUp`     | Increases the value by one large step          |
| `PageDown`   | Decreases the value by one large step          |
| `Home`       | Sets the value to the minimum                  |
| `End`        | Sets the value to the maximum                  |
| `Tab`        | Moves focus to / away from the thumb           |

### ARIA Attributes

- `Slider` renders with `role="group"` via Base UI.
- `SliderThumb` renders with `role="slider"`.
- `aria-valuenow`, `aria-valuemin`, and `aria-valuemax` are set on the thumb.
- `aria-orientation` is set based on the `orientation` prop.
- `aria-disabled` is set when the slider is disabled.
- `SliderOutput` is linked to the thumb via `aria-describedby` for screen reader announcements.
- Screen readers announce the current value and range when the thumb receives focus.
</page>

<page url="https://prototyper-ui.com/docs/components/switch" slug="components/switch">
# Switch
> A toggle switch built on Base UI
URL: https://prototyper-ui.com/docs/components/switch
Base UI reference: https://base-ui.com/react/components/switch
```tsx
import { Switch, SwitchTrack, SwitchThumb } from "@/components/ui/switch"

export default function SwitchDemo() {
  return (
    <Switch>
      <SwitchTrack>
        <SwitchThumb />
      </SwitchTrack>
      Low power mode
    </Switch>
  )
}
```

## Installation

```bash
pnpm dlx shadcn@latest add https://prototyper-ui.com/r/switch.json
```

This will add the following files to your project:

- `components/ui/switch.tsx`

## Usage

```tsx
import {
  Switch,
  SwitchTrack,
  SwitchThumb,
} from "@/components/ui/switch"

<Switch>
  <SwitchTrack>
    <SwitchThumb />
  </SwitchTrack>
  Airplane Mode
</Switch>
```

## Anatomy

```tsx
<Switch>
  <SwitchTrack>
    <SwitchThumb>
      <SwitchIcon /> {/* optional */}
    </SwitchThumb>
  </SwitchTrack>
  {/* label text */}
</Switch>
```

| Sub-component | `data-slot`      | Purpose                                     | Required |
| ------------- | ---------------- | ------------------------------------------- | -------- |
| `Switch`      | `switch`         | Root component with label and switch control | Yes      |
| `SwitchTrack` | `switch-track`   | The sliding track background                | Yes      |
| `SwitchThumb` | `switch-thumb`   | The draggable thumb indicator               | Yes      |
| `SwitchIcon`  | `switch-icon`    | Optional icon wrapper inside the thumb      | No       |

## Examples

### Sizes
```tsx
import { Switch, SwitchTrack, SwitchThumb } from "@/components/ui/switch"

export default function SwitchSizes() {
  return (
    <div className="flex flex-col gap-4">
      <Switch size="sm">
        <SwitchTrack>
          <SwitchThumb />
        </SwitchTrack>
        Small
      </Switch>
      <Switch size="md">
        <SwitchTrack>
          <SwitchThumb />
        </SwitchTrack>
        Medium
      </Switch>
      <Switch size="lg">
        <SwitchTrack>
          <SwitchThumb />
        </SwitchTrack>
        Large
      </Switch>
    </div>
  )
}
```

### With Icon
```tsx
import { Check } from "lucide-react"

import { Switch, SwitchTrack, SwitchThumb, SwitchIcon } from "@/components/ui/switch"

export default function SwitchWithIcon() {
  return (
    <Switch size="lg">
      <SwitchTrack>
        <SwitchThumb>
          <SwitchIcon>
            <Check className="text-muted-foreground group-data-checked:text-primary" />
          </SwitchIcon>
        </SwitchThumb>
      </SwitchTrack>
      Notifications
    </Switch>
  )
}
```

### Label Left
```tsx
import { Switch, SwitchTrack, SwitchThumb } from "@/components/ui/switch"

export default function SwitchLabelLeft() {
  return (
    <Switch className="flex-row-reverse justify-between w-64">
      <SwitchTrack>
        <SwitchThumb />
      </SwitchTrack>
      Notifications
    </Switch>
  )
}
```

### Disabled
```tsx
import { Switch, SwitchTrack, SwitchThumb } from "@/components/ui/switch"

export default function SwitchDisabled() {
  return (
    <Switch disabled>
      <SwitchTrack>
        <SwitchThumb />
      </SwitchTrack>
      Airplane Mode
    </Switch>
  )
}
```

### Read Only
```tsx
import { Switch, SwitchTrack, SwitchThumb } from "@/components/ui/switch"

export default function SwitchReadonly() {
  return (
    <Switch readOnly defaultChecked>
      <SwitchTrack>
        <SwitchThumb />
      </SwitchTrack>
      Bluetooth
    </Switch>
  )
}
```

## Styling

### Data Slots

Use `data-slot` attributes to target specific parts of the switch:

| Slot name      | Element                        |
| -------------- | ------------------------------ |
| `switch`       | Root wrapper (label + track)   |
| `switch-track` | The sliding track background   |
| `switch-thumb` | The circular thumb indicator   |

### Customization Examples

```css
/* Make the switch track wider */
[data-slot="switch-track"] {
  @apply w-12 h-6;
}

/* Custom checked track color */
[data-slot="switch"] [data-slot="switch-track"] {
  @apply group-data-checked:bg-green-600;
}
```

```tsx
{/* Override styles via className */}
<Switch className="gap-4">Wide gap label</Switch>
```

## API Reference

### Switch

Root component that manages on/off state and renders a track with thumb.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` | - | Controlled checked state |
| `defaultChecked` | `boolean` | `false` | Initial checked state for uncontrolled usage |
| `onCheckedChange` | `(checked: boolean, event: Event) => void` | - | Callback when checked state changes |
| `disabled` | `boolean` | `false` | Whether the switch is disabled |
| `readOnly` | `boolean` | `false` | Whether the switch is read-only |
| `required` | `boolean` | `false` | Whether the switch is required |
| `name` | `string` | - | Name attribute for form submission |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Label content rendered next to the switch |

All [Base UI Switch.Root props](https://base-ui.com/react/components/switch) are forwarded via `...props`.

## Accessibility

### Keyboard Interactions

| Key     | Action                               |
| ------- | ------------------------------------ |
| `Space` | Toggles the switch on/off            |
| `Tab`   | Moves focus to / away from the switch |

### ARIA Attributes

- Renders with `role="switch"` via Base UI.
- `aria-checked` is set to `true` or `false` based on the switch state.
- `aria-disabled` is set when the switch is disabled.
- `aria-readonly` is set when the switch is read-only.
- Screen readers announce the label and the on/off state.
</page>

<page url="https://prototyper-ui.com/docs/components/tabs" slug="components/tabs">
# Tabs
> Tabbed content panels built on Base UI
URL: https://prototyper-ui.com/docs/components/tabs
Base UI reference: https://base-ui.com/react/components/tabs
```tsx
import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/ui/tabs"

export default function TabsDemo() {
  return (
    <Tabs defaultValue="account">
      <TabsList aria-label="Manage your account">
        <TabsTrigger value="account">Account</TabsTrigger>
        <TabsTrigger value="notifications">Notifications</TabsTrigger>
        <TabsTrigger value="billing">Billing</TabsTrigger>
      </TabsList>
      <TabsContent value="account">
        Update your name, email, and profile photo.
      </TabsContent>
      <TabsContent value="notifications">
        Choose which notifications you receive and how.
      </TabsContent>
      <TabsContent value="billing">
        Manage your subscription plan and payment method.
      </TabsContent>
    </Tabs>
  )
}
```

## Installation

```bash
pnpm dlx shadcn@latest add https://prototyper-ui.com/r/tabs.json
```

This will add the following files to your project:

- `components/ui/tabs.tsx`

## Usage

```tsx
import {
  Tabs,
  TabsList,
  TabsTrigger,
  TabsContent,
} from "@/components/ui/tabs"

<Tabs defaultValue="tab-1">
  <TabsList>
    <TabsTrigger value="tab-1">Tab 1</TabsTrigger>
    <TabsTrigger value="tab-2">Tab 2</TabsTrigger>
  </TabsList>
  <TabsContent value="tab-1">Content 1</TabsContent>
  <TabsContent value="tab-2">Content 2</TabsContent>
</Tabs>
```

## Anatomy

```tsx
<Tabs>
  <TabsList>
    <TabsTrigger />
    <TabsTrigger />
  </TabsList>
  <TabsContent />
  <TabsContent />
</Tabs>
```

| Sub-component  | `data-slot`    | Purpose                                  | Required |
| -------------- | -------------- | ---------------------------------------- | -------- |
| `Tabs`         | `tabs`         | Root provider, manages active tab state  | Yes      |
| `TabsList`     | `tabs-list`    | Container for tab triggers               | Yes      |
| `TabsTrigger`  | `tabs-trigger` | Button that activates a tab panel        | Yes      |
| `TabsContent`  | `tabs-content` | Content panel associated with a trigger  | Yes      |

## Examples

### Disabled
```tsx
import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/ui/tabs"

export default function TabsDisabled() {
  return (
    <Tabs defaultValue="mouse">
      <TabsList aria-label="Input settings">
        <TabsTrigger value="mouse" disabled>Mouse Settings</TabsTrigger>
        <TabsTrigger value="keyboard" disabled>Keyboard Settings</TabsTrigger>
        <TabsTrigger value="gamepad" disabled>Gamepad Settings</TabsTrigger>
      </TabsList>
      <TabsContent value="mouse">Mouse Settings</TabsContent>
      <TabsContent value="keyboard">Keyboard Settings</TabsContent>
      <TabsContent value="gamepad">Gamepad Settings</TabsContent>
    </Tabs>
  )
}
```

### Disabled Dynamic
```tsx
import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/ui/tabs"

export default function TabsDisabledDynamic() {
  let tabs = [
    { id: 1, title: "Mouse settings" },
    { id: 2, title: "Keyboard settings" },
    { id: 3, title: "Gamepad settings" },
  ]

  return (
    <Tabs defaultValue="1">
      <TabsList aria-label="Input settings">
        {tabs.map((item) => (
          <TabsTrigger key={item.id} value={String(item.id)} disabled={item.id === 2}>
            {item.title}
          </TabsTrigger>
        ))}
      </TabsList>
      {tabs.map((item) => (
        <TabsContent key={item.id} value={String(item.id)}>
          {item.title}
        </TabsContent>
      ))}
    </Tabs>
  )
}
```

### Disabled Items
```tsx
import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/ui/tabs"

export default function TabsDisabledItems() {
  return (
    <Tabs defaultValue="mouse">
      <TabsList aria-label="Input settings">
        <TabsTrigger value="mouse">Mouse Settings</TabsTrigger>
        <TabsTrigger value="keyboard">Keyboard Settings</TabsTrigger>
        <TabsTrigger value="gamepad" disabled>
          Gamepad Settings
        </TabsTrigger>
      </TabsList>
      <TabsContent value="mouse">Mouse Settings</TabsContent>
      <TabsContent value="keyboard">Keyboard Settings</TabsContent>
      <TabsContent value="gamepad">Gamepad Settings</TabsContent>
    </Tabs>
  )
}
```

### Dynamic
```tsx
"use client"

import React from "react"

import { Button } from "@/components/ui/button"
import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/ui/tabs"

export default function TabsDynamic() {
  let [tabs, setTabs] = React.useState([
    { id: 1, title: "Tab 1", content: "Tab body 1" },
    { id: 2, title: "Tab 2", content: "Tab body 2" },
    { id: 3, title: "Tab 3", content: "Tab body 3" },
  ])

  let addTab = () => {
    setTabs((tabs) => [
      ...tabs,
      {
        id: tabs.length + 1,
        title: `Tab ${tabs.length + 1}`,
        content: `Tab body ${tabs.length + 1}`,
      },
    ])
  }

  let removeTab = () => {
    if (tabs.length > 1) {
      setTabs((tabs) => tabs.slice(0, -1))
    }
  }

  return (
    <Tabs defaultValue="1">
      <div className="flex justify-between gap-3">
        <TabsList aria-label="Dynamic tabs" style={{ flex: 1 }}>
          {tabs.map((item) => (
            <TabsTrigger key={item.id} value={String(item.id)}>
              {item.title}
            </TabsTrigger>
          ))}
        </TabsList>
        <div className="flex gap-3">
          <Button variant="outline" onClick={addTab}>
            Add tab
          </Button>
          <Button variant="outline" onClick={removeTab}>
            Remove tab
          </Button>
        </div>
      </div>
      {tabs.map((item) => (
        <TabsContent key={item.id} value={String(item.id)}>
          {item.content}
        </TabsContent>
      ))}
    </Tabs>
  )
}
```

### Focus
```tsx
import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/ui/tabs"
import { Input } from "@/components/ui/textfield"

export default function TabsFocus() {
  return (
    <Tabs defaultValue="1">
      <TabsList aria-label="Notes app">
        <TabsTrigger value="1">Jane Doe</TabsTrigger>
        <TabsTrigger value="2">John Doe</TabsTrigger>
        <TabsTrigger value="3">Joe Bloggs</TabsTrigger>
      </TabsList>
      <TabsContent value="1">
        <label>
          Leave a note for Jane: <Input type="text" />
        </label>
      </TabsContent>
      <TabsContent value="2">Senatus Populusque Romanus.</TabsContent>
      <TabsContent value="3">Alea jacta est.</TabsContent>
    </Tabs>
  )
}
```

### Vertical
```tsx
import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/ui/tabs"

export default function TabsVertical() {
  return (
    <Tabs defaultValue="1" orientation="vertical">
      <TabsList aria-label="Chat log orientation example">
        <TabsTrigger value="1">John Doe</TabsTrigger>
        <TabsTrigger value="2">Jane Doe</TabsTrigger>
        <TabsTrigger value="3">Joe Bloggs</TabsTrigger>
      </TabsList>
      <TabsContent value="1">There is no prior chat history with John Doe.</TabsContent>
      <TabsContent value="2">There is no prior chat history with Jane Doe.</TabsContent>
      <TabsContent value="3">
        There is no prior chat history with Joe Bloggs.
      </TabsContent>
    </Tabs>
  )
}
```

## Styling

### Data Slots

Use `data-slot` attributes to target specific parts of the tabs:

| Slot name      | Element                              |
| -------------- | ------------------------------------ |
| `tabs`         | Root wrapper                         |
| `tabs-list`    | Container for tab triggers           |
| `tabs-trigger` | Individual tab button                |
| `tabs-content` | Tab panel content area               |

### Customization Examples

```css
/* Make the tab list full-width */
[data-slot="tabs-list"] {
  @apply w-full;
}

/* Custom active tab style */
[data-slot="tabs-trigger"][data-active] {
  @apply bg-primary text-primary-foreground;
}
```

```tsx
{/* Override list variant via className */}
<TabsList className="bg-transparent gap-2">
  <TabsTrigger value="tab-1">Tab 1</TabsTrigger>
  <TabsTrigger value="tab-2">Tab 2</TabsTrigger>
</TabsList>
```

## API Reference

### Tabs

Root component that manages active tab state and context.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `any` | - | Initial active tab for uncontrolled usage |
| `value` | `any` | - | Controlled active tab value |
| `onValueChange` | `(value: any) => void` | - | Callback when the active tab changes |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Layout direction of the tabs |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Tabs content |

All [Base UI Tabs.Root props](https://base-ui.com/react/components/tabs) are forwarded via `...props`.

### TabsList

Container for tab triggers with variant styling.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "line"` | `"default"` | Visual style variant for the tab list |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Tab triggers |

All [Base UI Tabs.List props](https://base-ui.com/react/components/tabs) are forwarded via `...props`.

### TabsTrigger

Button that activates a tab panel when clicked.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `any` | - | Value linking this trigger to a panel |
| `disabled` | `boolean` | `false` | Whether the trigger is disabled |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Tab label content |

All [Base UI Tabs.Tab props](https://base-ui.com/react/components/tabs) are forwarded via `...props`.

### TabsContent

Content panel that is shown when its associated trigger is active.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `any` | - | Value linking this panel to a trigger |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Panel content |

All [Base UI Tabs.Panel props](https://base-ui.com/react/components/tabs) are forwarded via `...props`.

### tabsListVariants

A `cva` helper exported for use outside of the `<TabsList>` component (e.g., applying tab list styles to custom elements).

```tsx
import { tabsListVariants } from "@/components/ui/tabs"

<div className={tabsListVariants({ variant: "line" })}>Custom tab list</div>
```

## Accessibility

### Keyboard Interactions

| Key              | Action                                                              |
| ---------------- | ------------------------------------------------------------------- |
| `ArrowRight`     | Moves focus to the next tab trigger (horizontal orientation)        |
| `ArrowLeft`      | Moves focus to the previous tab trigger (horizontal orientation)    |
| `ArrowDown`      | Moves focus to the next tab trigger (vertical orientation)          |
| `ArrowUp`        | Moves focus to the previous tab trigger (vertical orientation)      |
| `Home`           | Moves focus to the first tab trigger                                |
| `End`            | Moves focus to the last tab trigger                                 |
| `Space`          | Activates the focused tab trigger                                   |
| `Enter`          | Activates the focused tab trigger                                   |
| `Tab`            | Moves focus into the active tab panel, then to the next element     |

### ARIA Attributes

- The tab list renders with `role="tablist"`.
- Each trigger renders with `role="tab"` and `aria-selected` indicating whether it is active.
- Each content panel renders with `role="tabpanel"`.
- `aria-controls` on each trigger links to its corresponding panel.
- `aria-labelledby` on each panel links back to its corresponding trigger.
- `aria-orientation` is set on the tab list based on the `orientation` prop.
- `aria-disabled` is set on disabled tab triggers.
</page>

<page url="https://prototyper-ui.com/docs/components/textfield" slug="components/textfield">
# TextField
> A text input with label and validation built on Base UI
URL: https://prototyper-ui.com/docs/components/textfield
Base UI reference: https://base-ui.com/react/components/field
```tsx
import { FieldLabel } from "@/components/ui/field"
import { Input, TextField } from "@/components/ui/textfield"

export default function TextFieldDemo() {
  return (
    <TextField>
      <FieldLabel>First name</FieldLabel>
      <Input />
    </TextField>
  )
}
```

## Installation

```bash
pnpm dlx shadcn@latest add https://prototyper-ui.com/r/textfield.json
```

This will add the following files to your project:

- `components/ui/textfield.tsx`

> **Note:** This component depends on [Field](/docs/components/field). It will be installed automatically.

## Usage

```tsx
import { TextField, Input } from "@/components/ui/textfield"
import { FieldLabel } from "@/components/ui/field"

<TextField>
  <FieldLabel>Name</FieldLabel>
  <Input placeholder="Enter your name" />
</TextField>
```

## Anatomy

```tsx
<TextField>
  <FieldLabel />
  <Input />
  <FieldDescription />
  <FieldError />
</TextField>
```

Or with `TextArea`:

```tsx
<TextField>
  <FieldLabel />
  <TextArea />
  <FieldDescription />
  <FieldError />
</TextField>
```

| Sub-component     | `data-slot`          | Purpose                                      | Required |
| ----------------- | -------------------- | -------------------------------------------- | -------- |
| `TextField`       | `text-field`         | Root field wrapper, provides form context     | Yes      |
| `Input`           | `input`              | Single-line text input                        | Yes*     |
| `TextArea`        | `textarea`           | Multi-line text input                         | Yes*     |
| `FieldLabel`      | `field-label`        | Label for the text field                      | No       |
| `FieldDescription`| `field-description`  | Descriptive helper text                       | No       |
| `FieldError`      | `field-error`        | Validation error message                      | No       |

\* Use either `Input` or `TextArea`, not both.

## Examples

### Description
```tsx
import { FieldLabel } from "@/components/ui/field"
import { Input, TextField } from "@/components/ui/textfield"

export default function TextFieldDescription() {
  return (
    <TextField>
      <FieldLabel>Email</FieldLabel>
      <Input className="w-fit" />
      <span className="text-sm text-muted-foreground">
        Enter an email for us to contact you about your order.
      </span>
    </TextField>
  )
}
```

### Disabled
```tsx
import { FieldLabel } from "@/components/ui/field"
import { Input, TextField } from "@/components/ui/textfield"

export default function TextFieldDisabled() {
  return (
    <TextField disabled>
      <FieldLabel>Email</FieldLabel>
      <Input />
    </TextField>
  )
}
```

### Multiline
```tsx
import { FieldLabel } from "@/components/ui/field"
import { TextArea, TextField } from "@/components/ui/textfield"

export default function TextFieldMultiline() {
  return (
    <TextField>
      <FieldLabel>Comment</FieldLabel>
      <TextArea />
    </TextField>
  )
}
```

### Read Only
```tsx
import { FieldLabel } from "@/components/ui/field"
import { Input, TextField } from "@/components/ui/textfield"

export default function TextFieldReadonly() {
  return (
    <TextField>
      <FieldLabel>Email</FieldLabel>
      <Input defaultValue="abc@adobe.com" readOnly />
    </TextField>
  )
}
```

### Reusable
```tsx
import { ProtoTextField } from "@/components/ui/textfield"

export default function TextfieldReusable() {
  return (
    <div className="flex flex-col gap-4">
      <ProtoTextField label="Name" description="Enter your name" />
      <ProtoTextField
        textArea
        label="Review"
        description="Leave a review"
      />
    </div>
  )
}
```

### Validation
```tsx
import { Button } from "@/components/ui/button"
import { FieldError, FieldLabel } from "@/components/ui/field"
import { Input, TextField } from "@/components/ui/textfield"

export default function TextFieldValidation() {
  return (
    <form className="flex flex-col gap-2">
      <TextField className="group">
        <FieldLabel>Email</FieldLabel>
        <Input name="email" type="email" required />
        <FieldError />
      </TextField>
      <Button className="w-fit" type="submit">
        Submit
      </Button>
    </form>
  )
}
```

## Styling

### Data Slots

Use `data-slot` attributes to target specific parts of the text field:

| Slot name          | Element                        |
| ------------------ | ------------------------------ |
| `text-field`       | Root wrapper (`Field.Root`)    |
| `input`            | The `<input>` element          |
| `textarea`         | The `<textarea>` element       |

### Customization Examples

```css
/* Remove border and shadow from all inputs */
[data-slot="input"] {
  @apply border-0 shadow-none;
}

/* Custom focus ring color */
[data-slot="input"]:focus {
  @apply ring-2 ring-blue-500;
}
```

```tsx
{/* Override size via className */}
<Input className="h-12 text-lg" placeholder="Large input" />
```

## API Reference

### TextField

Root wrapper that provides form field context. Built on Base UI `Field.Root`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Field content (label, input, etc.) |

All [Base UI Field props](https://base-ui.com/react/components/field) are forwarded via `...props`.

### Input

A styled single-line text input built on Base UI `Input`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "default" \| "lg"` | `"default"` | Size of the input |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Input props](https://base-ui.com/react/components/input) are forwarded via `...props`.

### TextArea

A styled multi-line text area using a native `<textarea>` element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All native `textarea` props are forwarded via `...props`.

### ProtoTextField

A convenience wrapper that composes `TextField`, `Input`/`TextArea`, `FieldLabel`, `FieldDescription`, and `FieldError` into a single component.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | - | Label text for the field |
| `description` | `string` | - | Helper description text |
| `errorMessage` | `string` | - | Validation error message |
| `textArea` | `boolean` | - | Render a TextArea instead of Input |
| `inputProps` | `InputPrimitive.Props & VariantProps` | - | Props passed to the Input sub-component |
| `textAreaProps` | `React.ComponentProps<"textarea">` | - | Props passed to the TextArea sub-component |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Custom content (replaces Input/TextArea) |

All [Base UI Field props](https://base-ui.com/react/components/field) are forwarded via `...props`.

### inputVariants

A `cva` helper exported for applying input styles outside of the `<Input>` component.

```tsx
import { inputVariants } from "@/components/ui/textfield"

<input className={inputVariants({ size: "sm" })} />
```

## Accessibility

### Keyboard Interactions

| Key     | Action                                          |
| ------- | ----------------------------------------------- |
| `Tab`   | Moves focus into or out of the input            |

### ARIA Attributes

- `TextField` renders as a Base UI `Field.Root`, automatically associating the label, description, and error message with the input via `aria-labelledby`, `aria-describedby`, and `aria-errormessage`.
- When validation fails, `data-invalid` is set on the input and the field root.
- `data-disabled` is set when the field is disabled.
- Screen readers announce the label, description, and any error messages associated with the input.
</page>

<page url="https://prototyper-ui.com/docs/components/toggle" slug="components/toggle">
# Toggle
> A two-state toggle button built on Base UI
URL: https://prototyper-ui.com/docs/components/toggle
Base UI reference: https://base-ui.com/react/components/toggle
```tsx
import { FontBoldIcon } from "@radix-ui/react-icons"

import { Toggle } from "@/components/ui/toggle"

export default function ToggleDemo() {
  return (
    <Toggle aria-label="Toggle italic">
      <FontBoldIcon className="size-4" />
    </Toggle>
  )
}
```

## Installation

```bash
pnpm dlx shadcn@latest add https://prototyper-ui.com/r/toggle.json
```

This will add the following files to your project:

- `components/ui/toggle.tsx`

## Usage

```tsx
import { Toggle } from "@/components/ui/toggle"

<Toggle>Bold</Toggle>
```

## Examples

### Outline
```tsx
import { FontItalicIcon } from "@radix-ui/react-icons"

import { Toggle } from "@/components/ui/toggle"

export default function ToggleOutline() {
  return (
    <Toggle variant="outline" aria-label="Toggle italic">
      <FontItalicIcon className="size-4" />
    </Toggle>
  )
}
```

### Small
```tsx
import { FontItalicIcon } from "@radix-ui/react-icons"

import { Toggle } from "@/components/ui/toggle"

export default function ToggleSm() {
  return (
    <Toggle size="sm" aria-label="Toggle italic">
      <FontItalicIcon className="size-4" />
    </Toggle>
  )
}
```

### Large
```tsx
import { FontItalicIcon } from "@radix-ui/react-icons"

import { Toggle } from "@/components/ui/toggle"

export default function ToggleLg() {
  return (
    <Toggle size="lg" aria-label="Toggle italic">
      <FontItalicIcon className="size-4" />
    </Toggle>
  )
}
```

### Disabled
```tsx
import { UnderlineIcon } from "@radix-ui/react-icons"

import { Toggle } from "@/components/ui/toggle"

export default function ToggleDisabled() {
  return (
    <Toggle aria-label="Toggle italic" disabled>
      <UnderlineIcon className="size-4" />
    </Toggle>
  )
}
```

### With Text
```tsx
import { FontItalicIcon } from "@radix-ui/react-icons"

import { Toggle } from "@/components/ui/toggle"

export default function ToggleWithText() {
  return (
    <Toggle aria-label="Toggle italic">
      <FontItalicIcon className="mr-2 size-4" />
      Italic
    </Toggle>
  )
}
```

## Styling

### Data Slots

Use `data-slot` attributes to target the toggle in CSS:

| Slot name | Element             |
| --------- | ------------------- |
| `toggle`  | The `<button>` root |

### Customization Examples

```css
/* Style all pressed toggles */
[data-slot="toggle"][aria-pressed="true"] {
  @apply bg-primary text-primary-foreground;
}
```

```tsx
{/* Use className for one-off overrides */}
<Toggle className="rounded-full">Pill Toggle</Toggle>
```

## API Reference

### Toggle

A two-state toggle button that can be pressed or unpressed.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "outline"` | `"default"` | Visual style variant |
| `size` | `"default" \| "sm" \| "lg"` | `"default"` | Size of the toggle |
| `pressed` | `boolean` | - | Controlled pressed state |
| `onPressedChange` | `(pressed: boolean) => void` | - | Callback when pressed state changes |
| `defaultPressed` | `boolean` | `false` | Initial pressed state for uncontrolled usage |
| `disabled` | `boolean` | `false` | Whether the toggle is disabled |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Toggle content |

All [Base UI Toggle props](https://base-ui.com/react/components/toggle) are forwarded via `...props`.

### toggleVariants

A `cva` helper exported for use outside of the `<Toggle>` component.

```tsx
import { toggleVariants } from "@/components/ui/toggle"

<button className={toggleVariants({ variant: "outline", size: "sm" })}>Custom Toggle</button>
```

## Accessibility

### Keyboard Interactions

| Key     | Action                                 |
| ------- | -------------------------------------- |
| `Space` | Toggles the pressed state              |
| `Enter` | Toggles the pressed state              |
| `Tab`   | Moves focus to / away from the toggle  |

### ARIA Attributes

- Renders as a `<button>` element with `aria-pressed` attribute.
- `aria-pressed="true"` when the toggle is in the pressed state, `aria-pressed="false"` when unpressed.
- Screen readers announce the toggle as a toggle button with its current pressed/unpressed state.
- `disabled` attribute is set when the toggle is disabled.
</page>

<page url="https://prototyper-ui.com/docs/components/toolbar" slug="components/toolbar">
# Toolbar
> A toolbar container with keyboard navigation built on Base UI
URL: https://prototyper-ui.com/docs/components/toolbar
Base UI reference: https://base-ui.com/react/components/toolbar
```tsx
"use client"

import {
  FontBoldIcon,
  FontItalicIcon,
  UnderlineIcon,
} from "@radix-ui/react-icons"
import { Button } from "@/components/ui/button"
import {
  Checkbox,
  CheckboxControl,
  CheckboxIndicator,
} from "@/components/ui/checkbox"
import { Toggle } from "@/components/ui/toggle"
import { Toolbar, ToolbarSeparator } from "@/components/ui/toolbar"

export default function ToolbarDemo() {
  return (
    <Toolbar aria-label="Text formatting">
      <div role="group" aria-label="Style" className="space-x-2">
        <Toggle className="w-10" variant="outline" aria-label="Bold">
          <FontBoldIcon className="size-4" />
        </Toggle>
        <Toggle className="w-10" variant="outline" aria-label="Italic">
          <FontItalicIcon className="size-4" />
        </Toggle>
        <Toggle className="w-10" variant="outline" aria-label="Underline">
          <UnderlineIcon className="size-4" />
        </Toggle>
      </div>
      <ToolbarSeparator orientation="vertical" />
      <div role="group" aria-label="Clipboard" className={"space-x-2"}>
        <Button variant="outline">Copy</Button>
        <Button variant="outline">Paste</Button>
        <Button variant="outline">Cut</Button>
      </div>
      <ToolbarSeparator orientation="vertical" />
      <Checkbox>
        <CheckboxControl>
          <CheckboxIndicator />
        </CheckboxControl>
        Night Mode
      </Checkbox>
    </Toolbar>
  )
}
```

## Installation

```bash
pnpm dlx shadcn@latest add https://prototyper-ui.com/r/toolbar.json
```

This will add the following files to your project:

- `components/ui/toolbar.tsx`

## Usage

```tsx
import {
  Toolbar,
  ToolbarButton,
  ToolbarSeparator,
} from "@/components/ui/toolbar"

<Toolbar>
  <ToolbarButton>Bold</ToolbarButton>
  <ToolbarButton>Italic</ToolbarButton>
  <ToolbarSeparator />
  <ToolbarButton>Link</ToolbarButton>
</Toolbar>
```

## Anatomy

```tsx
<Toolbar>
  <ToolbarGroup>
    <ToolbarButton />
    <ToolbarButton />
  </ToolbarGroup>
  <ToolbarSeparator />
  <ToolbarGroup>
    <ToolbarLink />
  </ToolbarGroup>
  <ToolbarInput />
</Toolbar>
```

| Sub-component      | `data-slot`          | Purpose                                      | Required |
| ------------------ | -------------------- | -------------------------------------------- | -------- |
| `Toolbar`          | `toolbar`            | Root container with keyboard navigation      | Yes      |
| `ToolbarButton`    | `toolbar-button`     | A button within the toolbar                  | No       |
| `ToolbarLink`      | `toolbar-link`       | A link within the toolbar                    | No       |
| `ToolbarGroup`     | `toolbar-group`      | Groups related toolbar items together        | No       |
| `ToolbarSeparator` | `toolbar-separator`  | Visual separator between toolbar items       | No       |
| `ToolbarInput`     | `toolbar-input`      | A text input within the toolbar              | No       |

## Examples

### Vertical
```tsx
"use client"

import {
  CursorArrowIcon,
  MagicWandIcon,
  MoveIcon,
  Pencil1Icon,
  Pencil2Icon,
} from "@radix-ui/react-icons"
import { Button } from "@/components/ui/button"
import { Toolbar, ToolbarSeparator } from "@/components/ui/toolbar"

export default function ToolbarVerticalDemo() {
  return (
    <Toolbar aria-label="Tools" orientation="vertical">
      <div role="group" aria-label="Select" className="flex flex-col gap-2">
        <Button variant="outline" size="icon" aria-label="Move">
          <MoveIcon className="size-4" />
        </Button>
        <Button variant="outline" size="icon" aria-label="Rectangle">
          <CursorArrowIcon className="size-4" />
        </Button>
        <Button variant="outline" size="icon" aria-label="Polygon">
          <MagicWandIcon className="size-4" />
        </Button>
      </div>
      <ToolbarSeparator orientation="horizontal" />
      <div role="group" aria-label="Draw" className={"flex flex-col gap-2"}>
        <Button variant="outline" size="icon" aria-label="Brush">
          <Pencil2Icon className="size-4" />
        </Button>
        <Button variant="outline" size="icon" aria-label="Pencil">
          <Pencil1Icon className="size-4" />
        </Button>
      </div>
    </Toolbar>
  )
}
```

## Styling

### Data Slots

Use `data-slot` attributes to target specific parts of the toolbar:

| Slot name           | Element                               |
| ------------------- | ------------------------------------- |
| `toolbar`           | Root toolbar container                |
| `toolbar-button`    | Button element within the toolbar     |
| `toolbar-link`      | Link element within the toolbar       |
| `toolbar-group`     | Group wrapper for related items       |
| `toolbar-separator` | Separator line between items          |
| `toolbar-input`     | Text input within the toolbar         |

### Customization Examples

```css
/* Add a border around the toolbar */
[data-slot="toolbar"] {
  @apply rounded-lg border bg-background p-1;
}

/* Style toolbar buttons with more padding */
[data-slot="toolbar-button"] {
  @apply px-4;
}
```

```tsx
{/* Override styles via className */}
<Toolbar className="rounded-lg border bg-background p-1">
  <ToolbarButton className="px-4">Bold</ToolbarButton>
</Toolbar>
```

## API Reference

### Toolbar

Root container that provides keyboard navigation between toolbar items.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Layout direction of the toolbar |
| `disabled` | `boolean` | `false` | Disables all items in the toolbar |
| `loop` | `boolean` | `true` | Whether keyboard navigation loops around |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Toolbar content |

All [Base UI Toolbar.Root props](https://base-ui.com/react/components/toolbar) are forwarded via `...props`.

### ToolbarButton

A button within the toolbar that participates in keyboard navigation.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether the button is disabled |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Button content |

All [Base UI Toolbar.Button props](https://base-ui.com/react/components/toolbar) are forwarded via `...props`.

### ToolbarLink

A link within the toolbar that participates in keyboard navigation.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` | - | The URL the link points to |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Link content |

All [Base UI Toolbar.Link props](https://base-ui.com/react/components/toolbar) are forwarded via `...props`.

### ToolbarGroup

Groups related toolbar items together visually and semantically.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Disables all items in the group |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Group content |

All [Base UI Toolbar.Group props](https://base-ui.com/react/components/toolbar) are forwarded via `...props`.

### ToolbarSeparator

A visual separator between toolbar items or groups.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `"vertical"` | Direction of the separator line |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Toolbar.Separator props](https://base-ui.com/react/components/toolbar) are forwarded via `...props`.

### ToolbarInput

A text input within the toolbar that participates in keyboard navigation.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Toolbar.Input props](https://base-ui.com/react/components/toolbar) are forwarded via `...props`.

## Accessibility

### Keyboard Interactions

| Key              | Action                                                      |
| ---------------- | ----------------------------------------------------------- |
| `Tab`            | Moves focus into the toolbar (focuses the first/last active item) |
| `ArrowRight`     | Moves focus to the next toolbar item (horizontal orientation) |
| `ArrowLeft`      | Moves focus to the previous toolbar item (horizontal orientation) |
| `ArrowDown`      | Moves focus to the next toolbar item (vertical orientation)  |
| `ArrowUp`        | Moves focus to the previous toolbar item (vertical orientation) |
| `Home`           | Moves focus to the first toolbar item                        |
| `End`            | Moves focus to the last toolbar item                         |
| `Space` / `Enter`| Activates the focused toolbar button or link                 |

### ARIA Attributes

- `Toolbar` renders with `role="toolbar"` by default via Base UI.
- `aria-orientation` is set to match the `orientation` prop.
- `aria-disabled` is set on the toolbar when `disabled` is `true`.
- Toolbar items are part of a single tab stop; arrow keys navigate between items within the toolbar.
- Focus management follows the roving tabindex pattern so only one item is tabbable at a time.
</page>

<page url="https://prototyper-ui.com/docs/components/tooltip" slug="components/tooltip">
# Tooltip
> A tooltip that appears on hover built on Base UI
URL: https://prototyper-ui.com/docs/components/tooltip
Base UI reference: https://base-ui.com/react/components/tooltip
```tsx
import { Pencil1Icon } from "@radix-ui/react-icons"

import { Button } from "@/components/ui/button"
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"

export default function TooltipDemo() {
  return (
    <Tooltip>
      <TooltipTrigger render={<Button variant="outline" size="icon" aria-label="Edit" />}>
        <Pencil1Icon className="size-4" />
      </TooltipTrigger>
      <TooltipContent>Edit</TooltipContent>
    </Tooltip>
  )
}
```

## Installation

```bash
pnpm dlx shadcn@latest add https://prototyper-ui.com/r/tooltip.json
```

This will add the following files to your project:

- `components/ui/tooltip.tsx`

## Usage

```tsx
import {
  Tooltip,
  TooltipTrigger,
  TooltipContent,
  TooltipProvider,
} from "@/components/ui/tooltip"

<TooltipProvider>
  <Tooltip>
    <TooltipTrigger>Hover me</TooltipTrigger>
    <TooltipContent>Tooltip text</TooltipContent>
  </Tooltip>
</TooltipProvider>
```

## Anatomy

```tsx
<TooltipProvider>
  <Tooltip>
    <TooltipTrigger />
    <TooltipContent />
  </Tooltip>
</TooltipProvider>
```

| Sub-component      | `data-slot`          | Purpose                                        | Required |
| ------------------ | -------------------- | ---------------------------------------------- | -------- |
| `TooltipProvider`  | `tooltip-provider`   | Shared delay and configuration for tooltips    | Yes      |
| `Tooltip`          | `tooltip`            | Root provider, manages open/close state        | Yes      |
| `TooltipTrigger`   | `tooltip-trigger`    | Element that triggers the tooltip on hover     | Yes      |
| `TooltipContent`   | `tooltip-content`    | The popup displaying tooltip text              | Yes      |

## Examples

### Cross Offset
```tsx
import { ArrowRightIcon } from "@radix-ui/react-icons"

import { Button } from "@/components/ui/button"
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"

export default function TooltipOffset() {
  return (
    <Tooltip>
      <TooltipTrigger render={<Button variant="outline" size="icon" aria-label="Edit" />}>
        <ArrowRightIcon className="size-4" />
      </TooltipTrigger>
      <TooltipContent side="bottom" alignOffset={60}>
        This will shift over to the right.
      </TooltipContent>
    </Tooltip>
  )
}
```

### Disabled
```tsx
import { Pencil1Icon } from "@radix-ui/react-icons"

import { Button } from "@/components/ui/button"
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"

export default function TooltipDisabled() {
  return (
    <Tooltip disabled>
      <TooltipTrigger render={<Button variant="outline" size="icon" aria-label="Edit" />}>
        <Pencil1Icon className="size-4" />
      </TooltipTrigger>
      <TooltipContent>Edit</TooltipContent>
    </Tooltip>
  )
}
```

### Offset
```tsx
import { ArrowUpIcon } from "@radix-ui/react-icons"

import { Button } from "@/components/ui/button"
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"

export default function TooltipOffset() {
  return (
    <Tooltip>
      <TooltipTrigger render={<Button variant="outline" size="icon" aria-label="Edit" />}>
        <ArrowUpIcon className="size-4" />
      </TooltipTrigger>
      <TooltipContent side="top" sideOffset={50}>
        This will shift up.
      </TooltipContent>
    </Tooltip>
  )
}
```

### Position
```tsx
import { Button } from "@/components/ui/button"
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"

export default function TooltipPosition() {
  return (
    <div className="flex gap-4">
      <Tooltip>
        <TooltipTrigger render={<Button variant="outline" />}>
          Left
        </TooltipTrigger>
        <TooltipContent side="left">
          <p>Add to library</p>
        </TooltipContent>
      </Tooltip>
      <Tooltip>
        <TooltipTrigger render={<Button variant="outline" />}>
          Up
        </TooltipTrigger>
        <TooltipContent side="top">
          <p>Add to library</p>
        </TooltipContent>
      </Tooltip>
      <Tooltip>
        <TooltipTrigger render={<Button variant="outline" />}>
          Down
        </TooltipTrigger>
        <TooltipContent side="bottom">
          <p>Add to library</p>
        </TooltipContent>
      </Tooltip>
      <Tooltip>
        <TooltipTrigger render={<Button variant="outline" />}>
          Right
        </TooltipTrigger>
        <TooltipContent side="right">
          <p>Add to library</p>
        </TooltipContent>
      </Tooltip>
    </div>
  )
}
```

## Styling

### Data Slots

Use `data-slot` attributes to target specific parts of the tooltip:

| Slot name            | Element                          |
| -------------------- | -------------------------------- |
| `tooltip-provider`   | Shared provider (no DOM rendered)|
| `tooltip`            | Root provider (no DOM rendered)  |
| `tooltip-trigger`    | The trigger element              |
| `tooltip-content`    | The popup panel                  |
| `tooltip-arrow`      | Arrow element pointing to trigger|

### Customization Examples

```css
/* Change tooltip background */
[data-slot="tooltip-content"] {
  @apply bg-primary text-primary-foreground;
}

/* Style the tooltip arrow */
[data-slot="tooltip-arrow"] {
  @apply bg-primary fill-primary;
}
```

```tsx
{/* Override styles via className */}
<TooltipContent className="bg-destructive text-destructive-foreground">
  This action is destructive
</TooltipContent>
```

## API Reference

### TooltipProvider

Shared provider that configures delay and grouping behavior for all child tooltips.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `delay` | `number` | `0` | Delay in ms before tooltips appear |

All [Base UI Tooltip.Provider props](https://base-ui.com/react/components/tooltip) are forwarded via `...props`.

### Tooltip

Root component that manages open/close state for a single tooltip.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | - | Controlled open state |
| `onOpenChange` | `(open: boolean) => void` | - | Callback when open state changes |
| `defaultOpen` | `boolean` | `false` | Initial open state for uncontrolled usage |

All [Base UI Tooltip.Root props](https://base-ui.com/react/components/tooltip) are forwarded via `...props`.

### TooltipTrigger

Element that triggers the tooltip on hover and focus.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |

All [Base UI Tooltip.Trigger props](https://base-ui.com/react/components/tooltip) are forwarded via `...props`.

### TooltipContent

The popup panel displaying the tooltip text, rendered inside a portal with a positioner.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `"top" \| "bottom" \| "left" \| "right"` | `"top"` | Preferred side relative to trigger |
| `sideOffset` | `number` | `8` | Gap between trigger and popup |
| `align` | `"start" \| "center" \| "end"` | `"center"` | Alignment relative to the trigger |
| `alignOffset` | `number` | `0` | Offset from the alignment edge |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Tooltip content |

All [Base UI Tooltip.Popup props](https://base-ui.com/react/components/tooltip) are forwarded via `...props`.

## Accessibility

### Keyboard Interactions

| Key       | Action                                          |
| --------- | ----------------------------------------------- |
| `Tab`     | Moves focus to the trigger, showing the tooltip |
| `Escape`  | Closes the tooltip                              |

### ARIA Attributes

- `TooltipContent` receives `role="tooltip"` via Base UI.
- The trigger element receives `aria-describedby` pointing to the tooltip content.
- Tooltips appear on both hover and focus, ensuring keyboard accessibility.
- The tooltip includes an arrow element for visual connection to the trigger.
- Screen readers announce tooltip content when the trigger receives focus.
</page>

<page url="https://prototyper-ui.com/docs/design-principles" slug="design-principles">
# Design Principles
> Core principles that guide Prototyper UI's design and development.
URL: https://prototyper-ui.com/docs/design-principles
Prototyper UI follows a set of core principles that prioritize ownership, beauty, consistency, and developer experience. These principles shape every decision — from token naming to component API design.

## 1. You Own The Code

Components are files you copy into your project, read, edit, and extend. There is no hidden abstraction layer, no runtime CSS-in-JS, no provider you must wrap your app in. You install a component, it lands in your codebase, and it's yours.

This is the [shadcn philosophy](https://ui.shadcn.com/docs): the component library is a starting point, not a dependency.

```bash
# Install a component — it copies source into your project
npx shadcn@latest add https://prototyper-ui.com/r/button.json
```

```tsx
// You get a real file you can edit
// registry/ui/button.tsx
function Button({ className, variant, size, ...props }) {
  return (
    <ButtonPrimitive
      className={cn(buttonVariants({ variant, size, className }))}
      {...props}
    />
  )
}
```

**Why this matters:** No version lock-in. No waiting for upstream fixes. No fighting abstraction layers to customize behavior. You change the file, you change the component.

## 2. Base UI Native

Every interactive component is built on [Base UI](https://base-ui.com) — the unstyled primitive library from the Material UI team. Base UI handles the hard problems (focus management, keyboard navigation, ARIA attributes, scroll locking, portal rendering) so we focus entirely on design.

```tsx
// Base UI provides the behavior, we provide the style
import { Select as SelectPrimitive } from "@base-ui/react/select"

function SelectTrigger({ className, children, ...props }) {
  return (
    <SelectPrimitive.Trigger
      className={cn("flex h-9 w-full items-center ...", className)}
      {...props}
    >
      {children}
      <SelectPrimitive.Icon render={<ChevronsUpDownIcon />} />
    </SelectPrimitive.Trigger>
  )
}
```

**What Base UI gives us for free:**
- WCAG 2.1 AA compliance across all components
- Keyboard navigation (arrow keys, type-ahead, focus trapping)
- Screen reader announcements via ARIA attributes
- Data attributes (`data-open`, `data-disabled`, `data-highlighted`) as a public styling contract
- Portal rendering for overlays
- Scroll lock for modals

## 3. Beautiful by Default

Components should look exceptional without any customization. The design system uses:

- **OKLCH color space** — perceptually uniform, `color-mix()` works predictably for derived states
- **Multi-layer shadows** — three stacked shadow layers simulate realistic light (subtle edge shadow is critical for dark mode)
- **Role-based surfaces** — surfaces, overlays, and fields each have dedicated tokens and shadow tiers
- **Fluid easing** — `cubic-bezier(0.32, 0.72, 0, 1)` as the signature curve (Apple-style deceleration)
- **Gradient buttons** — the default button uses a three-layer gradient system with primary color ramps

Beauty is not decoration — it's the result of precise tokens, consistent spacing, and careful shadow/color relationships.

## 4. Role-Based Surfaces

Inspired by [HeroUI v3's surface system](https://v3.heroui.com), surfaces are categorized by their **role in the UI**, not by arbitrary elevation numbers:

| Role | Token | Shadow | Components |
|------|-------|--------|-----------|
| **Surface** | `bg-surface` | `shadow-surface` | Cards, panels, tabs |
| **Overlay** | `bg-overlay` | `shadow-overlay` | Dialogs, popovers, menus, dropdowns |
| **Field** | `bg-field-background` | `shadow-field` | Inputs, selects, comboboxes |

**Light mode** uses shadows for depth. **Dark mode** uses background lightness stepping — shadows are reduced or zeroed because dark surfaces already show depth through tonal difference.

Three surface tiers handle nesting (card-in-card):
- `bg-surface` — primary surface
- `bg-surface-secondary` — nested containers (derived via `color-mix`)
- `bg-surface-tertiary` — deeper nesting (derived via `color-mix`)

## 5. CSS Utilities for Consistency

Every component references shared CSS utilities instead of reimplementing focus, disabled, and invalid patterns. This guarantees identical behavior everywhere:

```css
/* Focus ring — buttons, links, interactive elements */
@utility focus-ring {
  outline: 2px solid var(--color-ring);
  outline-offset: 2px;
}

/* Focus ring — form fields (sits on border, no offset) */
@utility focus-field-ring {
  outline: 2px solid var(--color-ring);
  outline-offset: -1px;
}

/* Disabled state — universal across all components */
@utility status-disabled {
  opacity: 0.5;
  pointer-events: none;
  cursor: not-allowed;
}
```

```tsx
// Every component uses the same utilities
<Button className="focus-visible:focus-ring disabled:status-disabled" />
<Input className="focus-within:focus-field-ring data-disabled:status-disabled" />
<Toggle className="focus-visible:focus-ring data-disabled:status-disabled" />
```

**Why not per-component styles?** Because 5 different focus ring implementations (different widths, colors, offsets) is how inconsistency creeps in. One utility, one look, everywhere.

## 6. Flat Exports, shadcn-Compatible

Components use flat named exports — no `Object.assign` compound patterns, no dot notation. This is what shadcn users know and what LLMs generate best.

```tsx
// Named exports — clear, greppable, tree-shakeable
import {
  Select,
  SelectTrigger,
  SelectContent,
  SelectItem,
  SelectValue,
} from "@/components/ui/select"

<Select>
  <SelectTrigger>
    <SelectValue placeholder="Pick one" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="a">Option A</SelectItem>
    <SelectItem value="b">Option B</SelectItem>
  </SelectContent>
</Select>
```

Every component root and sub-component has a `data-slot` attribute for external targeting:

```css
/* Target any component part from outside */
[data-slot="select-trigger"] { /* ... */ }
[data-slot="select-content"] { /* ... */ }
```

## 7. Progressive Disclosure

Components work with minimal props and scale up as requirements grow. The simplest usage should be a single line; advanced usage reveals more knobs.

```tsx
// Level 1: Minimal — just works
<ComboboxInput placeholder="Search..." />

// Level 2: Control what's visible
<ComboboxInput placeholder="Search..." showClear showTrigger={false} />

// Level 3: Full composition
<InputGroup>
  <ComboboxPrimitive.Input className="..." />
  <InputGroupAddon align="inline-end">
    <ComboboxClear />
    <ComboboxTrigger />
  </InputGroupAddon>
</InputGroup>
```

## 8. CSS-First Animation

No JavaScript animation libraries. All transitions and animations use CSS, data attributes for state, and `prefers-reduced-motion` support.

```css
/* Overlay enter/exit via Tailwind animate utilities */
data-open:animate-in data-closed:animate-out
data-closed:fade-out-0 data-open:fade-in-0
data-closed:zoom-out-95 data-open:zoom-in-95

/* Interactive elements use transition-colors */
transition-colors duration-200

/* Easing tokens from the design system */
--ease-out-fluid: cubic-bezier(0.32, 0.72, 0, 1);
--ease-smooth: cubic-bezier(0.4, 0, 0.2, 1);
```

**Reduced motion is respected automatically.** All components use Tailwind's `motion-reduce:` variant which maps to both `prefers-reduced-motion` media query and `data-reduce-motion` attribute.

## 9. Type Safety

Full TypeScript with strict mode. Component props are derived from Base UI's type definitions, extended where needed:

```tsx
// Props extend Base UI types — full IntelliSense
function SelectTrigger({
  className,
  size = "default",
  children,
  ...props
}: SelectPrimitive.Trigger.Props & {
  size?: "sm" | "default" | "lg"
}) {
  // ...
}
```

Variant types are generated by `class-variance-authority`:

```tsx
import { cva, type VariantProps } from "class-variance-authority"

const buttonVariants = cva("...", {
  variants: {
    variant: { default: "...", destructive: "...", outline: "..." },
    size: { default: "h-9", sm: "h-8", lg: "h-10" },
  },
})

// VariantProps<typeof buttonVariants> gives you { variant?: "default" | ... }
```

## 10. LLM-Friendly

Prototyper UI is designed to be generated correctly by AI. Every component follows the same patterns:

- **Consistent file structure:** `"use client"`, imports, component functions, exports
- **Consistent naming:** `ComponentName` + `ComponentNameSubPart` (e.g., `Select`, `SelectTrigger`, `SelectContent`)
- **Consistent props:** `className` + `...props` spread on every component
- **Consistent styling:** Tailwind utilities, `cn()` for merging, `data-slot` for identification
- **Rich examples:** Every component has multiple examples showing common patterns
- **Structured docs:** MDX pages with live previews, installation commands, and usage snippets

When an LLM reads one component, it understands all of them.

---

## Design Token Architecture

### Color Space: OKLCH

All colors use the OKLCH color space with `color-mix(in oklab)` for derived states:

```css
/* Base token (manually defined per theme) */
--primary: 39.11% 0.084 240.8;

/* Derived hover state (90% base + 10% foreground) */
--primary-hover: color-mix(in oklab, oklch(var(--primary)) 90%, oklch(var(--primary-foreground)) 10%);

/* Derived soft variant (15% opacity) */
--primary-soft: color-mix(in oklab, oklch(var(--primary)) 15%, transparent);
```

**Why OKLCH?** Perceptually uniform — a 10% mix shift looks like 10% regardless of the base color. HSL-based mixing produces unpredictable results across hues.

### Shadow System

Three semantic shadow tiers, mode-adaptive:

| Tier | Light Mode | Dark Mode | Used For |
|------|-----------|-----------|----------|
| `shadow-surface` | Multi-layer subtle shadow | None (tonal contrast instead) | Cards, panels |
| `shadow-field` | Subtle shadow + 1px edge | None | Form inputs |
| `shadow-overlay` | Heavy multi-layer shadow | Subtle 1px inset white glow | Popovers, menus, dialogs |

### What We Derive vs. Define Manually

| Manually defined | Derived via `color-mix()` |
|---|---|
| Base colors (`--primary`, `--destructive`, etc.) | Hover states (90% base + 10% foreground) |
| Foreground colors (`--primary-foreground`, etc.) | Soft variants (15% base + transparent) |
| Color ramps (`--primary-light/middle/dark`) | Surface tiers (secondary, tertiary) |
| Surface/overlay/field backgrounds | Border/separator progressions |

**Why not derive everything?** Tested with 5 brand colors — ramp derivation collapses for light colors, washes chroma for dark colors. Foreground can't be auto-derived (green needs dark text in both modes). Manual definition where it matters, derivation where it's safe.

---

## Comparison with Other Libraries

| Aspect | shadcn/ui | HeroUI v3 | Prototyper UI |
|--------|-----------|-----------|---------------|
| **Primitive library** | Radix UI | React Aria | Base UI |
| **Ownership model** | Copy-paste | Package dependency | Copy-paste |
| **Color space** | HSL | OKLCH | OKLCH |
| **Surface system** | Ad-hoc (3 tokens) | Role-based (surface/overlay/field) | Role-based (surface/overlay/field) |
| **Shadow system** | Size-based (sm/md/lg) | Semantic (surface/overlay) | Semantic (surface/field/overlay) |
| **Animation** | CSS + Tailwind | CSS + GPU accelerated | CSS + Tailwind |
| **Component API** | Flat exports | Compound (dot notation) | Flat exports |
| **Styling** | Tailwind-in-component | BEM + CSS layers | Tailwind-in-component |
| **Dark mode shadows** | Same as light | Zeroed / inset glow | Zeroed / inset glow |
</page>

<page url="https://prototyper-ui.com/docs/for-agents/llms-txt" slug="for-agents/llms-txt">
# LLMs.txt
> Machine-readable documentation endpoints for AI assistants
URL: https://prototyper-ui.com/docs/for-agents/llms-txt
Prototyper UI exposes several plain-text endpoints optimized for LLM consumption, following the [llms.txt convention](https://llmstxt.org).

## Endpoints

| URL | Purpose |
|-----|---------|
| [`/llms.txt`](/llms.txt) | Index of all docs pages and components |
| [`/llms-full.txt`](/llms-full.txt) | Complete documentation — all pages in one file |
| [`/llms-components.txt`](/llms-components.txt) | All components with full TypeScript source and examples |
| `/llms/{slug}` | Individual page LLM text (e.g. [`/llms/button`](/llms/button)) |
| `/llms/components/{name}` | Component docs + source via full path (e.g. [`/llms/components/button`](/llms/components/button)) |
| [`/prototyper-tokens.css`](/prototyper-tokens.css) | Complete OKLCH design tokens as a downloadable CSS file |

The `/llms/{slug}` endpoint is a catch-all: any docs page slug works, not just component names.

## Usage

**Claude Code — reference in conversation:**

```
@https://prototyper-ui.com/llms.txt
```

**Claude Code — add to CLAUDE.md:**

```markdown
## UI Library
See @https://prototyper-ui.com/llms.txt for available components.
```

**Cursor — add to `.cursorrules`:**

```
@Docs https://prototyper-ui.com/llms-full.txt
```

**Windsurf — add to rules file:**

```
#docs https://prototyper-ui.com/llms-full.txt
```

**Direct fetch:**

```bash
curl https://prototyper-ui.com/llms/button
curl https://prototyper-ui.com/llms-components.txt
```

## Response Format

All endpoints return `text/plain; charset=utf-8`. Component endpoints include:

- Frontmatter (title, description, docs URL, Base UI reference link)
- Full MDX documentation converted to plain markdown
- All `<ComponentPreview>` examples inlined as `tsx` code blocks
- Full TypeScript component source
- Additional examples not already shown in docs
</page>

<page url="https://prototyper-ui.com/docs/for-agents/mcp-server" slug="for-agents/mcp-server">
# MCP Server
> Give your AI assistant structured access to Prototyper UI components via the Model Context Protocol
URL: https://prototyper-ui.com/docs/for-agents/mcp-server
The `@prototyperai/mcp-server` package provides structured access to components, docs, and design tokens via the [Model Context Protocol](https://modelcontextprotocol.io).

## Setup

### Claude Code

```bash
claude mcp add prototyper-ui -- npx -y @prototyperai/mcp-server@latest
```

Or add to `.mcp.json` in your project:

```json
{
  "mcpServers": {
    "prototyper-ui": {
      "command": "npx",
      "args": ["-y", "@prototyperai/mcp-server@latest"]
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "prototyper-ui": {
      "command": "npx",
      "args": ["-y", "@prototyperai/mcp-server@latest"]
    }
  }
}
```

### Windsurf

Add to `.windsurf/mcp.json`:

```json
{
  "mcpServers": {
    "prototyper-ui": {
      "command": "npx",
      "args": ["-y", "@prototyperai/mcp-server@latest"]
    }
  }
}
```

### VS Code

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "prototyper-ui": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@prototyperai/mcp-server@latest"]
    }
  }
}
```

### Zed

Add to `.zed/settings.json`:

```json
{
  "context_servers": {
    "prototyper-ui": {
      "command": {
        "path": "npx",
        "args": ["-y", "@prototyperai/mcp-server@latest"]
      }
    }
  }
}
```

## Available Tools

| Tool | Description |
|------|-------------|
| `list_components` | List all available components with descriptions |
| `get_component_docs` | Full documentation, API reference, and usage examples |
| `get_component_source` | Full TypeScript source code for a component |
| `get_theme` | Complete OKLCH design tokens CSS |
| `search_docs` | Full-text search across all documentation |

## Resources

The server also exposes MCP resources for direct access:

| Resource URI | Content |
|-------------|---------|
| `prototyper://tokens/css` | Full design tokens CSS |
| `prototyper://docs/components/{name}` | Component documentation |

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `PROTOTYPER_UI_BASE_URL` | `https://prototyper-ui.com` | Override the base URL (useful for local development) |

## Local Development

Point the MCP server at your local docs instance:

```bash
PROTOTYPER_UI_BASE_URL=http://localhost:3333 npx @prototyperai/mcp-server@latest
```
</page>

<page url="https://prototyper-ui.com/docs/for-agents/skills" slug="for-agents/skills">
# Agent Skills
> Install a Prototyper UI skill into Claude Code, Cursor, OpenCode, and more
URL: https://prototyper-ui.com/docs/for-agents/skills
Agent skills give AI assistants inline access to Prototyper UI patterns, component APIs, and examples — without needing to fetch from the web on every request.

## Install (all detected tools)

```bash
curl -fsSL https://prototyper-ui.com/install.sh | bash
```

This detects and installs to: **Claude Code**, **Cursor**, **OpenCode**, **Codex CLI**, **Gemini CLI**.

## Manual install — Claude Code

```bash
claude skill add https://prototyper-ui.com/install.sh
```

Or using the install script with a custom name:

```bash
curl -fsSL https://prototyper-ui.com/install.sh | bash -s -- my-prototyper-ui
```

## What's included

The skill bundle contains:

| File | Purpose |
|------|---------|
| `SKILL.md` | Main skill definition: component list, patterns, theming, and pitfalls |
| `scripts/list.mjs` | Fetch and display all available components |
| `scripts/docs.mjs` | Fetch full docs + source for one or more components |
| `scripts/source.mjs` | Fetch component source code only |
| `scripts/theme.mjs` | Fetch complete OKLCH design tokens |

## Usage after install

Once installed, run scripts from within the skill directory:

```bash
# List all components
node ~/.claude/skills/prototyper-ui/scripts/list.mjs

# Get button docs and source
node ~/.claude/skills/prototyper-ui/scripts/docs.mjs button

# Get multiple component docs at once
node ~/.claude/skills/prototyper-ui/scripts/docs.mjs button dialog select

# Get component source only
node ~/.claude/skills/prototyper-ui/scripts/source.mjs button

# Get design tokens
node ~/.claude/skills/prototyper-ui/scripts/theme.mjs
```

## Skill content

The `SKILL.md` covers:

- Why Prototyper UI uses `@base-ui/react` instead of Radix UI
- All 19 available components with descriptions
- Component patterns: `"use client"`, `data-slot`, CVA, `cn()`, compound exports
- OKLCH color system and design token categories
- CSS utility classes (`focus-ring`, `status-disabled`, etc.)
- Animation guidelines and easing values
- Common pitfalls and how to avoid them
- Installation and project setup

## Environment variable

Override the base URL to use a local docs server:

```bash
PROTOTYPER_UI_BASE_URL=http://localhost:3333 node scripts/docs.mjs button
```
</page>

<page url="https://prototyper-ui.com/docs" slug="index">
# Introduction
> Beautiful components built on Base UI. Copy and paste into your apps.
URL: https://prototyper-ui.com/docs/index
## Prototyper UI

Prototyper UI is a collection of beautifully designed components built on [Base UI](https://base-ui.com). Components are styled with Tailwind CSS and can be installed via the shadcn CLI.

### Features

- Built on Base UI for accessible, unstyled primitives
- Styled with Tailwind CSS v4
- Dark mode support
- Themeable with CSS variables
- shadcn-compatible registry — install with `npx shadcn@latest add`

### Installation

Install components individually:

```bash
npx shadcn@latest add https://prototyper-ui.com/r/button.json
```

### Dependencies

Components are built with:

- [Base UI](https://base-ui.com) — Unstyled UI primitives
- [Tailwind CSS v4](https://tailwindcss.com) — Utility-first CSS
- [class-variance-authority](https://cva.style) — Variant management
- [tailwind-merge](https://github.com/dcastil/tailwind-merge) — Class merging
</page>

<page url="https://prototyper-ui.com/docs/installation" slug="installation">
# Installation
> How to set up Prototyper UI in your Next.js project with Tailwind CSS v4 and Base UI.
URL: https://prototyper-ui.com/docs/installation
## Requirements

Prototyper UI components require the following:

- [React](https://react.dev) 19+
- [Next.js](https://nextjs.org) 15+
- [Tailwind CSS](https://tailwindcss.com) v4
- [Base UI](https://base-ui.com) (`@base-ui/react`)

## Quick Start

### Option A: Prototyper UI CLI (Recommended)

Set up your project and add components with the Prototyper UI CLI:

```bash
npx @prototyperai/cli init       # tokens, utils, base styles
npx @prototyperai/cli add button # add components
```

Run `add` without arguments for an interactive component picker, or install everything at once:

```bash
npx @prototyperai/cli add --all
```

### Option B: shadcn CLI

If you already use shadcn, install any component directly from the registry:

```bash
npx shadcn@latest add https://prototyper-ui.com/r/button.json
```

This copies the component source into your project (typically `components/ui/button.tsx`) along with any required dependencies.

```bash
npx shadcn@latest add https://prototyper-ui.com/r/button.json https://prototyper-ui.com/r/dialog.json https://prototyper-ui.com/r/select.json
```

## Keeping Up to Date

```bash
npx @prototyperai/cli update    # check for component updates
npx @prototyperai/cli doctor    # verify project setup
```

## Manual Setup

If you prefer to set up manually or need to understand each step, follow this guide.

### 1. Install Dependencies

```bash
npm install @base-ui/react class-variance-authority clsx tailwind-merge
```

### 2. Add the `cn` Utility

Create `lib/utils.ts` in your project:

```ts
import { clsx, type ClassValue } from "clsx"
import { twMerge } from "tailwind-merge"

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}
```

### 3. Set Up CSS Tokens

Add the design tokens to your `globals.css`. The token system has four layers:

**Theme registration** — maps CSS custom properties to Tailwind utilities:

```css
@theme {
  /* Radius scale */
  --radius-xl: calc(var(--radius) + 4px);
  --radius-lg: var(--radius);
  --radius-md: calc(var(--radius) - 2px);
  --radius-sm: calc(var(--radius) - 4px);

  /* Colors — each generates bg-*, text-*, border-* utilities */
  --color-background: oklch(var(--background));
  --color-foreground: oklch(var(--foreground));
  --color-primary: oklch(var(--primary));
  --color-primary-foreground: oklch(var(--primary-foreground));
  /* ... see full token list in the Theming guide */

  /* Shadows — three semantic tiers */
  --shadow-surface: 0 2px 4px 0 oklch(0% 0 0 / 0.04), 0 1px 2px 0 oklch(0% 0 0 / 0.06), 0 0 0 1px oklch(0% 0 0 / 0.04);
  --shadow-field: 0 1px 2px 0 oklch(0% 0 0 / 0.05), 0 0 0 1px oklch(0% 0 0 / 0.04);
  --shadow-overlay: 0 8px 30px oklch(0% 0 0 / 0.12), 0 2px 8px oklch(0% 0 0 / 0.06), 0 0 0 1px oklch(0% 0 0 / 0.06);

  /* Easing curves */
  --ease-smooth: cubic-bezier(0.4, 0, 0.2, 1);
  --ease-out-fluid: cubic-bezier(0.32, 0.72, 0, 1);
  /* ... */
}
```

**Light mode tokens** (`:root`) — base OKLCH values for all colors, surfaces, and borders.

**Dark mode tokens** (`.dark`) — overrides for dark mode, including zeroed shadows where tonal contrast provides depth.

**CSS utilities** — shared focus, disabled, and invalid patterns used by every component:

```css
@utility focus-ring {
  outline: 2px solid var(--color-ring);
  outline-offset: 2px;
}

@utility focus-field-ring {
  outline: 2px solid var(--color-ring);
  outline-offset: -1px;
}

@utility status-disabled {
  opacity: 0.5;
  pointer-events: none;
  cursor: not-allowed;
}
```

For the complete `globals.css` file, see the [Theming](/docs/theming) guide.

### 4. Copy Component Files

Copy the component source from the registry into your `components/ui/` directory. Each component is a self-contained file that imports from `@base-ui/react` and `@/lib/utils`.

```tsx
// components/ui/button.tsx
"use client"

import { Button as ButtonPrimitive } from "@base-ui/react/button"
import { cva, type VariantProps } from "class-variance-authority"
import { cn } from "@/lib/utils"

// ... component implementation
```

## Token Overview

The design system organizes tokens into clear categories:

| Category | Examples | Purpose |
|----------|----------|---------|
| **Colors** | `--primary`, `--destructive`, `--success` | Brand and semantic colors (OKLCH values) |
| **Surfaces** | `--surface`, `--overlay`, `--field-background` | Role-based surface backgrounds |
| **Borders** | `--border`, `--border-light`, `--field-border` | Edge treatments at multiple weights |
| **Shadows** | `--shadow-surface`, `--shadow-field`, `--shadow-overlay` | Three semantic tiers, mode-adaptive |
| **Easings** | `--ease-smooth`, `--ease-out-fluid` | Animation timing functions |
| **Radius** | `--radius`, `--radius-sm`, `--radius-lg` | Border radius scale |
| **Derived** | `--primary-hover`, `--primary-soft` | Auto-computed via `color-mix()` |

## Dark Mode

Prototyper UI supports dark mode through the `.dark` class on the `<html>` element. The recommended approach uses [next-themes](https://github.com/paisan-s/next-themes):

### Using next-themes

```bash
npm install next-themes
```

```tsx
// app/layout.tsx
import { ThemeProvider } from "next-themes"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
          {children}
        </ThemeProvider>
      </body>
    </html>
  )
}
```

### How Dark Mode Works

The `.dark` class toggles all color tokens to their dark variants and adjusts the shadow system:

- **Colors** shift to darker backgrounds and lighter foregrounds
- **Shadows** are zeroed for `surface` and `field` (tonal contrast provides depth instead)
- **Overlay shadows** switch to a subtle white inset glow + deeper dark shadow
- **Derived colors** (`--primary-hover`, `--primary-soft`, etc.) auto-adapt via `color-mix()`

### Alternative: data-theme Attribute

You can also toggle dark mode via a `data-theme` attribute if you prefer:

```css
[data-theme="dark"] {
  /* Same dark mode token overrides as .dark */
}
```

### System Preference

To respect the user's OS setting without JavaScript:

```css
@media (prefers-color-scheme: dark) {
  :root {
    /* Dark mode token overrides */
  }
}
```

The `next-themes` approach with `enableSystem` handles this automatically and avoids flash of wrong theme on load.
</page>

<page url="https://prototyper-ui.com/docs/introduction" slug="introduction">
# Introduction
> A composable UI library built on Base UI with Tailwind CSS. Own every line of code.
URL: https://prototyper-ui.com/docs/introduction
## What is Prototyper UI?

Prototyper UI is a collection of beautifully designed, accessible components built on [Base UI](https://base-ui.com) and styled with [Tailwind CSS v4](https://tailwindcss.com). Components are copied into your project as source files — you own and control every line of code.

Install any component with a single command:

```bash
npx shadcn@latest add https://prototyper-ui.com/r/button.json
```

The component lands in your codebase as a real file you can read, edit, and extend. No runtime dependency, no version lock-in, no abstraction layer to fight.

## Design Principles

### Composable — Own the Code

Components follow the [shadcn model](https://ui.shadcn.com/docs): the library is a starting point, not a dependency. You install a component, it becomes your file. Need to change how a select renders its trigger? Open the file and change it.

### Beautiful by Default

The design system uses OKLCH color tokens, multi-layer shadows, role-based surfaces, and fluid easing curves. Components look exceptional without any customization. Beauty comes from precise tokens and consistent spacing — not decoration.

### Base UI Native

Every interactive component is built on [Base UI](https://base-ui.com), the unstyled primitive library from the Material UI team. Base UI handles focus management, keyboard navigation, ARIA attributes, scroll locking, and portal rendering. Prototyper UI handles design.

### LLM-Friendly

Every component follows identical patterns: `"use client"`, imports, component functions, exports. Consistent naming (`Select`, `SelectTrigger`, `SelectContent`), consistent props (`className` + `...props` spread), consistent styling (`cn()` + Tailwind + `data-slot`). When an LLM reads one component, it understands all of them.

## Comparison with Alternatives

| Feature | Prototyper UI | shadcn/ui | HeroUI | Radix Themes |
|---------|---------------|-----------|--------|--------------|
| **Primitive library** | Base UI | Radix UI | React Aria | Radix UI |
| **Styling** | Tailwind-in-component | Tailwind-in-component | Slots + Tailwind | CSS-in-JS |
| **Owns code** | Yes (copy-paste) | Yes (copy-paste) | No (npm) | No (npm) |
| **Color space** | OKLCH | HSL | HSL | Custom |
| **Surface system** | Role-based (surface/overlay/field) | Ad-hoc | Role-based | Ad-hoc |
| **Shadow system** | Semantic (surface/field/overlay) | Size-based (sm/md/lg) | Semantic | Size-based |
| **Component API** | Flat named exports | Flat named exports | Compound (dot notation) | Compound (dot notation) |
| **Dark mode shadows** | Zeroed / inset glow | Same as light | Zeroed / inset glow | Same as light |

## Architecture

Prototyper UI uses a **registry-based architecture**, compatible with the shadcn CLI:

```
Registry (prototyper-ui.com/r/*.json)
  → Component source files (registry/ui/*.tsx)
    → Your project (components/ui/*.tsx)
```

1. The **registry** hosts JSON manifests that describe each component, its source code, and its dependencies.
2. The **CLI** (`npx shadcn@latest add`) reads the manifest, resolves dependencies, and copies the component source into your project.
3. **Your project** owns the resulting files. Components import from `@/components/ui/*` and `@/lib/utils` — standard paths that work in any Next.js project.

### Key Dependencies

Every component builds on the same foundation:

- [**Base UI**](https://base-ui.com) (`@base-ui/react`) — Unstyled, accessible primitives
- [**Tailwind CSS v4**](https://tailwindcss.com) (`tailwindcss`) — Utility-first CSS framework
- [**class-variance-authority**](https://cva.style) (`class-variance-authority`) — Variant management for components
- [**tailwind-merge**](https://github.com/dcastil/tailwind-merge) (`tailwind-merge`) — Intelligent class merging
- [**clsx**](https://github.com/lukeed/clsx) (`clsx`) — Conditional class construction

### Utility Function

All components use a shared `cn()` utility that combines `clsx` and `tailwind-merge`:

```ts
// lib/utils.ts
import { clsx, type ClassValue } from "clsx"
import { twMerge } from "tailwind-merge"

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}
```

This lets you safely merge and override Tailwind classes when composing components.
</page>

<page url="https://prototyper-ui.com/docs/theming" slug="theming">
# Theming
> Customize colors, surfaces, and shadows using OKLCH tokens and CSS custom properties.
URL: https://prototyper-ui.com/docs/theming
Prototyper UI's design system is built on CSS custom properties using the OKLCH color space. Every color, surface, shadow, and easing curve is a token you can override.

## OKLCH Color System

All colors use the [OKLCH color space](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/oklch) — a perceptually uniform model where lightness, chroma, and hue are independent axes.

```css
/* OKLCH values: lightness chroma hue */
--primary: 39.11% 0.084 240.8;
```

### Why OKLCH?

- **Perceptually uniform** — a 10% lightness shift looks like 10% regardless of the base hue. HSL lightness is wildly inconsistent across colors.
- **Predictable color-mix()** — derived states (hover, soft) use `color-mix(in oklab)` and produce consistent results across the entire hue range.
- **Wide gamut** — OKLCH can represent P3 and Rec.2020 colors that HSL cannot.

### How Derived Colors Work

Hover states, soft variants, and surface tiers are computed automatically using `color-mix()`:

```css
/* Hover: 90% base + 10% paired foreground */
--primary-hover: color-mix(in oklab, oklch(var(--primary)) 90%, oklch(var(--primary-foreground)) 10%);

/* Soft variant: 15% base on transparent */
--primary-soft: color-mix(in oklab, oklch(var(--primary)) 15%, transparent);

/* Surface tiers: progressive foreground mixing */
--surface-secondary: color-mix(in oklab, oklch(var(--surface)) 94%, oklch(var(--surface-foreground)) 6%);
--surface-tertiary: color-mix(in oklab, oklch(var(--surface)) 88%, oklch(var(--surface-foreground)) 12%);
```

You only need to define the base color and its foreground — all interaction states derive automatically.

## Token Reference

### Base Colors

| Token | Description | Light Default |
|-------|-------------|---------------|
| `--background` | Page background | `100% 0 0` (white) |
| `--foreground` | Default text color | `14.05% 0.004 285.8` |
| `--radius` | Base border radius | `0.5rem` |

### Primary Ramp

| Token | Description | Light Default |
|-------|-------------|---------------|
| `--primary` | Primary brand color, buttons | `39.11% 0.084 240.8` |
| `--primary-foreground` | Text on primary backgrounds | `98.48% 0 0` |
| `--primary-light` | Gradient light stop | `75.84% 0.137 231.6` |
| `--primary-middle` | Gradient middle stop | `49.96% 0.118 242.2` |
| `--primary-dark` | Gradient dark stop | `39.20% 0.084 240.8` |

### Semantic Colors

| Token | Description |
|-------|-------------|
| `--secondary` / `--secondary-foreground` | Secondary actions, subtle buttons |
| `--muted` / `--muted-foreground` | Muted backgrounds, placeholder text |
| `--accent` / `--accent-foreground` | Accent highlights, hover backgrounds |
| `--destructive` / `--destructive-foreground` | Destructive actions, error states |
| `--success` / `--success-foreground` | Success states |
| `--warning` / `--warning-foreground` | Warning states |
| `--info` / `--info-foreground` | Informational states |

### Surfaces

| Token | Description |
|-------|-------------|
| `--surface` / `--surface-foreground` | Cards, panels, tabs |
| `--surface-secondary` | Nested containers (derived via `color-mix`) |
| `--surface-tertiary` | Deeper nesting (derived via `color-mix`) |
| `--overlay` / `--overlay-foreground` | Dialogs, popovers, menus |
| `--card` / `--card-foreground` | Card backgrounds |
| `--popover` / `--popover-foreground` | Popover backgrounds |

### Fields

| Token | Description |
|-------|-------------|
| `--field-background` | Input, select, combobox backgrounds |
| `--field-border` | Field border color |
| `--field-border-hover` | Field border on hover (derived) |
| `--field-border-invalid` | Field border on validation error (derived) |

### Borders

| Token | Description |
|-------|-------------|
| `--border` | Default border |
| `--border-light` | Subtle border (dividers, separators) |
| `--border-dark` | Emphasized border |
| `--input` | Input border (matches `--border`) |
| `--ring` | Focus ring color (matches `--primary`) |

### Shadows

| Token | Light Mode | Dark Mode |
|-------|-----------|-----------|
| `--shadow-surface` | Multi-layer subtle shadow | `none` |
| `--shadow-field` | Subtle shadow + 1px edge | `none` |
| `--shadow-overlay` | Heavy multi-layer shadow | 1px white inset glow + deep shadow |

### Easings

| Token | Value | Usage |
|-------|-------|-------|
| `--ease-smooth` | `cubic-bezier(0.4, 0, 0.2, 1)` | General transitions |
| `--ease-out-fluid` | `cubic-bezier(0.32, 0.72, 0, 1)` | Signature deceleration curve |
| `--ease-out-quad` | `cubic-bezier(0.25, 0.46, 0.45, 0.94)` | Subtle ease-out |
| `--ease-out-quart` | `cubic-bezier(0.165, 0.84, 0.44, 1)` | Pronounced ease-out |
| `--ease-in-quad` | `cubic-bezier(0.55, 0.085, 0.68, 0.53)` | Subtle ease-in |
| `--ease-in-quart` | `cubic-bezier(0.895, 0.03, 0.685, 0.22)` | Pronounced ease-in |
| `--ease-in-out-quad` | `cubic-bezier(0.455, 0.03, 0.515, 0.955)` | Symmetric ease |

### Derived Interaction Colors

These are auto-computed from base tokens — you typically do not override them:

| Token | Formula |
|-------|---------|
| `--primary-hover` | 90% `--primary` + 10% `--primary-foreground` |
| `--destructive-hover` | 90% `--destructive` + 10% `--destructive-foreground` |
| `--success-hover` | 90% `--success` + 10% `--success-foreground` |
| `--warning-hover` | 90% `--warning` + 10% `--warning-foreground` |
| `--accent-hover` | 92% `--accent` + 8% `--accent-foreground` |
| `--primary-soft` | 15% `--primary` on transparent |
| `--primary-soft-hover` | 20% `--primary` on transparent |
| `--destructive-soft` | 15% `--destructive` on transparent |
| `--destructive-soft-hover` | 20% `--destructive` on transparent |

## Customize Colors

Override any token in your `globals.css` to change the look of all components at once. Tokens use raw OKLCH values (lightness, chroma, hue) without the `oklch()` wrapper:

```css
:root {
  /* Change primary to a teal */
  --primary: 55% 0.15 180;
  --primary-foreground: 98% 0 0;
  --primary-light: 75% 0.12 175;
  --primary-middle: 60% 0.14 178;
  --primary-dark: 45% 0.13 182;

  /* Update the focus ring to match */
  --ring: 55% 0.15 180;
}

.dark {
  --primary: 40% 0.10 180;
  --primary-foreground: 95% 0.02 178;
  --primary-light: 75% 0.12 175;
  --primary-middle: 60% 0.14 178;
  --primary-dark: 45% 0.13 182;

  --ring: 70% 0.08 178;
}
```

All derived tokens (`--primary-hover`, `--primary-soft`, etc.) will auto-adapt because they use `color-mix()` with your new base values.

## Create a Custom Theme

Here is a full example of a custom theme with both light and dark modes. Copy this into your `globals.css` and adjust the values:

```css
:root {
  /* Base */
  --background: 100% 0 0;
  --foreground: 14.05% 0.004 285.8;
  --radius: 0.5rem;

  /* Primary — violet example */
  --primary: 50% 0.2 280;
  --primary-foreground: 98% 0 0;
  --primary-light: 75% 0.15 275;
  --primary-middle: 58% 0.18 278;
  --primary-dark: 42% 0.19 282;

  /* Secondary */
  --secondary: 96% 0.01 280;
  --secondary-foreground: 25% 0.03 280;

  /* Muted */
  --muted: 96% 0 0;
  --muted-foreground: 55% 0.01 285;

  /* Accent */
  --accent: 96% 0 0;
  --accent-foreground: 21% 0.006 285;

  /* Destructive */
  --destructive: 63% 0.21 25;
  --destructive-foreground: 98% 0 0;

  /* Borders */
  --border: 92% 0.004 286;
  --border-light: 96% 0 0;
  --border-dark: 80% 0.01 286;
  --input: 92% 0.004 286;
  --ring: 50% 0.2 280;

  /* Surfaces */
  --surface: 98% 0 0;
  --surface-foreground: 14% 0.004 285;
  --surface-secondary: color-mix(in oklab, oklch(var(--surface)) 94%, oklch(var(--surface-foreground)) 6%);
  --surface-tertiary: color-mix(in oklab, oklch(var(--surface)) 88%, oklch(var(--surface-foreground)) 12%);
  --overlay: 100% 0 0;
  --overlay-foreground: 14% 0.004 285;

  /* Cards & Popovers */
  --card: 98% 0 0;
  --card-foreground: 14% 0.004 285;
  --popover: 100% 0 0;
  --popover-foreground: 14% 0.004 285;

  /* Fields */
  --field-background: 100% 0 0;
  --field-border: 92% 0.004 286;
  --field-border-hover: color-mix(in oklab, oklch(var(--field-border)) 70%, oklch(var(--foreground)) 30%);
  --field-border-invalid: oklch(var(--destructive));

  /* Derived hover states — auto-adapt */
  --primary-hover: color-mix(in oklab, oklch(var(--primary)) 90%, oklch(var(--primary-foreground)) 10%);
  --destructive-hover: color-mix(in oklab, oklch(var(--destructive)) 90%, oklch(var(--destructive-foreground)) 10%);
  --accent-hover: color-mix(in oklab, oklch(var(--accent)) 92%, oklch(var(--accent-foreground)) 8%);

  /* Derived soft variants */
  --primary-soft: color-mix(in oklab, oklch(var(--primary)) 15%, transparent);
  --primary-soft-hover: color-mix(in oklab, oklch(var(--primary)) 20%, transparent);
  --destructive-soft: color-mix(in oklab, oklch(var(--destructive)) 15%, transparent);
  --destructive-soft-hover: color-mix(in oklab, oklch(var(--destructive)) 20%, transparent);
}

.dark {
  /* Base */
  --background: 14% 0.004 285;
  --foreground: 98% 0 0;

  /* Primary — violet dark mode */
  --primary: 35% 0.14 282;
  --primary-foreground: 95% 0.02 278;
  --primary-light: 75% 0.15 275;
  --primary-middle: 58% 0.18 278;
  --primary-dark: 42% 0.19 282;

  /* Secondary */
  --secondary: 28% 0.03 280;
  --secondary-foreground: 98% 0 0;

  /* Muted */
  --muted: 27% 0.006 286;
  --muted-foreground: 71% 0.013 286;

  /* Accent */
  --accent: 27% 0.006 286;
  --accent-foreground: 98% 0 0;

  /* Destructive */
  --destructive: 40% 0.13 26;
  --destructive-foreground: 98% 0 0;

  /* Borders */
  --border: 32% 0.007 286;
  --border-light: 37% 0.008 286;
  --border-dark: 23% 0.004 286;
  --input: 27% 0.006 286;
  --ring: 70% 0.1 278;

  /* Surfaces */
  --surface: 16% 0.006 285;
  --surface-foreground: 98% 0 0;
  --surface-secondary: color-mix(in oklab, oklch(var(--surface)) 94%, oklch(var(--surface-foreground)) 6%);
  --surface-tertiary: color-mix(in oklab, oklch(var(--surface)) 88%, oklch(var(--surface-foreground)) 12%);
  --overlay: 20% 0.008 285;
  --overlay-foreground: 98% 0 0;

  /* Cards & Popovers */
  --card: 16% 0.006 285;
  --card-foreground: 98% 0 0;
  --popover: 14% 0.004 285;
  --popover-foreground: 98% 0 0;

  /* Fields */
  --field-background: 16% 0.006 285;
  --field-border: 32% 0.007 286;
  --field-border-hover: color-mix(in oklab, oklch(var(--field-border)) 70%, oklch(var(--foreground)) 30%);
  --field-border-invalid: oklch(var(--destructive));

  /* Derived — same formulas, auto-adapt to dark values */
  --primary-hover: color-mix(in oklab, oklch(var(--primary)) 90%, oklch(var(--primary-foreground)) 10%);
  --destructive-hover: color-mix(in oklab, oklch(var(--destructive)) 90%, oklch(var(--destructive-foreground)) 10%);
  --accent-hover: color-mix(in oklab, oklch(var(--accent)) 92%, oklch(var(--accent-foreground)) 8%);
  --primary-soft: color-mix(in oklab, oklch(var(--primary)) 15%, transparent);
  --primary-soft-hover: color-mix(in oklab, oklch(var(--primary)) 20%, transparent);
  --destructive-soft: color-mix(in oklab, oklch(var(--destructive)) 15%, transparent);
  --destructive-soft-hover: color-mix(in oklab, oklch(var(--destructive)) 20%, transparent);

  /* Shadows — tonal contrast replaces shadows */
  --shadow-surface: none;
  --shadow-field: none;
  --shadow-overlay: 0 0 0 1px oklch(100% 0 0 / 0.08), 0 8px 30px oklch(0% 0 0 / 0.35);
}
```

### What to Define vs. What to Derive

| Define manually | Derived via `color-mix()` |
|-----------------|---------------------------|
| Base colors (`--primary`, `--destructive`, etc.) | Hover states (90% base + 10% foreground) |
| Foreground colors (`--primary-foreground`, etc.) | Soft variants (15% base + transparent) |
| Color ramps (`--primary-light/middle/dark`) | Surface tiers (secondary, tertiary) |
| Surface/overlay/field backgrounds | Border hover progressions |

Foreground colors cannot be auto-derived — green needs dark text in both modes, while blue needs light text in both modes. Ramp derivation (light/middle/dark stops) collapses for light colors and washes chroma for dark colors. Define where it matters, derive where it's safe.

## Runtime Theme Switching

### Toggle Dark Mode

Add or remove the `.dark` class on the `<html>` element:

```ts
// Toggle dark mode
document.documentElement.classList.toggle("dark")

// Set explicitly
document.documentElement.classList.add("dark")    // dark
document.documentElement.classList.remove("dark")  // light
```

With [next-themes](https://github.com/paisan-s/next-themes), use the `useTheme` hook:

```tsx
import { useTheme } from "next-themes"

function ThemeToggle() {
  const { theme, setTheme } = useTheme()

  return (
    <button onClick={() => setTheme(theme === "dark" ? "light" : "dark")}>
      Toggle theme
    </button>
  )
}
```

### data-theme Attribute

You can also switch themes using a `data-theme` attribute, which is useful when supporting multiple named themes beyond light/dark:

```html
<html data-theme="dark">
```

```css
[data-theme="dark"] {
  --background: 14.05% 0.004 285.8;
  --foreground: 98.48% 0 0;
  /* ... all dark mode overrides */
}
```

### Swap Color Themes at Runtime

To switch between color themes (e.g., different primary colors) at runtime, apply CSS custom property overrides via a class or attribute:

```css
[data-theme="violet"] {
  --primary: 50% 0.2 280;
  --primary-foreground: 98% 0 0;
  --primary-light: 75% 0.15 275;
  --primary-middle: 58% 0.18 278;
  --primary-dark: 42% 0.19 282;
  --ring: 50% 0.2 280;
}

[data-theme="violet"].dark {
  --primary: 35% 0.14 282;
  --primary-foreground: 95% 0.02 278;
  --ring: 70% 0.1 278;
}
```

```ts
// Switch color theme
document.documentElement.setAttribute("data-theme", "violet")
```

## Theme Builder

Use the interactive [Theme Builder](/themes) to preview color combinations and generate the CSS tokens for your custom theme.
</page>