# Prototyper UI — Component Reference

> Each component below includes documentation, full TypeScript source, and usage examples.
> Install: bunx @prototyperco/cli add {component} (or: pnpm dlx shadcn@latest add https://prototyper-ui.com/r/{component}.json)
<component name="accordion" url="https://prototyper-ui.com/docs/components/accordion">
# Accordion
> vertically stacked collapsible content panels
URL: https://prototyper-ui.com/docs/components/accordion
Base UI reference: https://base-ui.com/react/components/accordion
```tsx
import {
  Accordion,
  AccordionItem,
  AccordionTrigger,
  AccordionContent,
} from "@/components/ui/accordion";

export default function AccordionDemo() {
  return (
    <Accordion>
      <AccordionItem>
        <AccordionTrigger>What is Prototyper UI?</AccordionTrigger>
        <AccordionContent>
          A composable, design-first React component library built on Base UI
          primitives. It features shadcn-compatible distribution with copy-paste
          components.
        </AccordionContent>
      </AccordionItem>
      <AccordionItem>
        <AccordionTrigger>How do I install components?</AccordionTrigger>
        <AccordionContent>
          Use the shadcn CLI to add components to your project. Each component
          is a standalone file you can customize freely.
        </AccordionContent>
      </AccordionItem>
      <AccordionItem>
        <AccordionTrigger>Can I customize the styling?</AccordionTrigger>
        <AccordionContent>
          Yes. All components use Tailwind CSS and expose data-slot attributes
          for targeted styling. You own the source code and can modify anything.
        </AccordionContent>
      </AccordionItem>
    </Accordion>
  );
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/accordion.tsx`

## Usage

```tsx
import {
  Accordion,
  AccordionItem,
  AccordionTrigger,
  AccordionContent,
} from "@/components/ui/accordion";

<Accordion>
  <AccordionItem>
    <AccordionTrigger>Is it accessible?</AccordionTrigger>
    <AccordionContent>
      Yes. It adheres to the WAI-ARIA Accordion pattern.
    </AccordionContent>
  </AccordionItem>
</Accordion>;
```

## Anatomy

```tsx
<Accordion>
  <AccordionItem>
    <AccordionTrigger />
    <AccordionContent />
  </AccordionItem>
</Accordion>
```

| Sub-component      | `data-slot`         | Purpose                                   | Required |
| ------------------ | ------------------- | ----------------------------------------- | -------- |
| `Accordion`        | `accordion`         | Root provider, manages expanded state     | Yes      |
| `AccordionItem`    | `accordion-item`    | Wrapper for a single collapsible section  | Yes      |
| `AccordionTrigger` | `accordion-trigger` | Button that toggles the panel open/closed | Yes      |
| `AccordionContent` | `accordion-content` | Collapsible content panel                 | Yes      |

## Examples

### Disabled

```tsx
import {
  Accordion,
  AccordionItem,
  AccordionTrigger,
  AccordionContent,
} from "@/components/ui/accordion";

export default function AccordionDisabled() {
  return (
    <Accordion disabled>
      <AccordionItem>
        <AccordionTrigger>What is Prototyper UI?</AccordionTrigger>
        <AccordionContent>
          A composable, design-first React component library built on Base UI
          primitives.
        </AccordionContent>
      </AccordionItem>
      <AccordionItem>
        <AccordionTrigger>How do I install components?</AccordionTrigger>
        <AccordionContent>
          Use the shadcn CLI to add components to your project.
        </AccordionContent>
      </AccordionItem>
      <AccordionItem>
        <AccordionTrigger>Can I customize the styling?</AccordionTrigger>
        <AccordionContent>
          Yes. All components use Tailwind CSS and expose data-slot attributes
          for targeted styling.
        </AccordionContent>
      </AccordionItem>
    </Accordion>
  );
}
```

## Styling

### Data Slots

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

| Slot name                | Element                          |
| ------------------------ | -------------------------------- |
| `accordion`              | Root wrapper                     |
| `accordion-item`         | Individual collapsible section   |
| `accordion-trigger`      | Toggle button (includes chevron) |
| `accordion-trigger-icon` | Chevron icon inside the trigger  |
| `accordion-content`      | Collapsible content panel        |

### Customization Examples

```css
/* Remove border between items */
[data-slot="accordion-item"] {
  @apply border-b-0;
}

/* Custom trigger icon color */
[data-slot="accordion-trigger-icon"] {
  @apply text-primary;
}
```

```tsx
{
  /* Override content padding via className */
}
<AccordionContent className="pb-6">{/* ... */}</AccordionContent>;
```

## API Reference

### Accordion

Root component that manages the expanded/collapsed state of all items.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `multiple` | `boolean` | `false` | Whether multiple items can be open at the same time |
| `loopFocus` | `boolean` | `true` | Whether to loop keyboard focus back to the first item when the end is reached |
| `keepMounted` | `boolean` | `false` | Whether panels should remain in the DOM when closed |
| `hiddenUntilFound` | `boolean` | `false` | Enables browser search to find and expand panel contents |
| `orientation` | `"horizontal" \| "vertical"` | `"vertical"` | Direction of roving focus navigation |
| `defaultValue` | `number[]` | - | Initially open item indices for uncontrolled usage |
| `value` | `number[]` | - | Controlled open item indices |
| `onValueChange` | `(value: number[]) => void` | - | Callback when the set of open items changes |
| `disabled` | `boolean` | `false` | Whether all items are disabled |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Accordion items |

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

### AccordionItem

Wrapper for a single collapsible section containing a trigger and content panel.

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

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

### AccordionTrigger

Button that toggles the visibility of the associated content panel.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether the trigger is disabled |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Trigger label content |

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

### AccordionContent

Collapsible content panel that animates open and closed.

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

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

## Accessibility

### Keyboard Interactions

| Key         | Action                                         |
| ----------- | ---------------------------------------------- |
| `Space`     | Toggles the focused accordion item open/closed |
| `Enter`     | Toggles the focused accordion item open/closed |
| `ArrowDown` | Moves focus to the next accordion trigger      |
| `ArrowUp`   | Moves focus to the previous accordion trigger  |
| `Home`      | Moves focus to the first accordion trigger     |
| `End`       | Moves focus to the last accordion trigger      |
| `Tab`       | Moves focus to the next focusable element      |

### ARIA Attributes

- Each trigger renders with `role="button"` inside a heading element.
- `aria-expanded` indicates whether the associated panel is open.
- `aria-controls` on each trigger links to its corresponding content panel.
- `aria-disabled` is set on disabled triggers.
- Each content panel renders with `role="region"`.
- `aria-labelledby` on each panel links back to its corresponding trigger.

## Compose

This component is available in [`@prototyperco/compose`](/docs/compose).

### Catalog Definition

```typescript title="accordion.catalog.ts"
import { z } from "zod";
import { defineComponent } from "@prototyperco/compose/catalog";

export default defineComponent({
  description: "A collapsible accordion with expandable sections",
  props: z.object({
    items: z
      .array(
        z.object({
          title: z.string().describe("Header text for the accordion item"),
          value: z.string().describe("Unique identifier for the item"),
        }),
      )
      .describe("Accordion items"),
    type: z
      .enum(["single", "multiple"])
      .optional()
      .describe("Whether one or multiple items can be open at once"),
    collapsible: z
      .boolean()
      .optional()
      .describe("Whether an open item can be collapsed"),
  }),
  example: {
    items: [
      { title: "What is your refund policy?", value: "refund" },
      { title: "How do I contact support?", value: "support" },
      { title: "Can I change my plan?", value: "plan" },
    ],
    type: "single",
    collapsible: true,
  },
});
```

### Example Spec

```json
{
  "root": "faq",
  "elements": {
    "faq": {
      "type": "Accordion",
      "props": {
        "items": [
          { "title": "What is your refund policy?", "value": "refund" },
          { "title": "How do I contact support?", "value": "support" },
          { "title": "Can I change my plan?", "value": "plan" }
        ],
        "type": "single",
        "collapsible": true
      },
      "children": ["refund_content", "support_content", "plan_content"]
    },
    "refund_content": {
      "type": "Text",
      "props": { "content": "We offer a 30-day money-back guarantee." }
    },
    "support_content": {
      "type": "Text",
      "props": { "content": "Email us at support@example.com." }
    },
    "plan_content": {
      "type": "Text",
      "props": { "content": "Yes, you can upgrade or downgrade at any time." }
    }
  }
}
```

Learn more in the [Compose documentation](/docs/compose).

## Full Component Source

```tsx
"use client";

export {
  Accordion,
  AccordionItem,
  AccordionTrigger,
  AccordionContent,
} from "@prototyperco/ui/components/accordion";
```
</component>

<component name="alert" url="https://prototyper-ui.com/docs/components/alert">
# Alert
> A callout for important messages with status variants
URL: https://prototyper-ui.com/docs/components/alert
```tsx
import { Info } from "lucide-react";
import { Alert, AlertTitle, AlertDescription } from "@/components/ui/alert";

export default function AlertDemo() {
  return (
    <Alert>
      <Info />
      <div>
        <AlertTitle>Heads up!</AlertTitle>
        <AlertDescription>
          You can add components to your app using the CLI.
        </AlertDescription>
      </div>
    </Alert>
  );
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/alert.tsx`

## Usage

```tsx
import { Alert, AlertTitle, AlertDescription } from "@/components/ui/alert";

<Alert>
  <AlertTitle>Heads up!</AlertTitle>
  <AlertDescription>
    You can add components to your app using the CLI.
  </AlertDescription>
</Alert>;
```

## Anatomy

```tsx
<Alert>
  <Icon />
  <div>
    <AlertTitle />
    <AlertDescription />
  </div>
</Alert>
```

| Sub-component      | `data-slot`         | Purpose                          | Required |
| ------------------ | ------------------- | -------------------------------- | -------- |
| `Alert`            | `alert`             | Root container with role="alert" | Yes      |
| `AlertTitle`       | `alert-title`       | Heading for the alert            | No       |
| `AlertDescription` | `alert-description` | Supporting message text          | No       |

## Examples

### Destructive

```tsx
import { AlertCircle } from "lucide-react";
import { Alert, AlertTitle, AlertDescription } from "@/components/ui/alert";

export default function AlertDestructive() {
  return (
    <Alert variant="destructive">
      <AlertCircle />
      <div>
        <AlertTitle>Error</AlertTitle>
        <AlertDescription>
          Your session has expired. Please log in again.
        </AlertDescription>
      </div>
    </Alert>
  );
}
```

### Success

```tsx
import { CheckCircle2 } from "lucide-react";
import { Alert, AlertTitle, AlertDescription } from "@/components/ui/alert";

export default function AlertSuccess() {
  return (
    <Alert variant="success">
      <CheckCircle2 />
      <div>
        <AlertTitle>Success</AlertTitle>
        <AlertDescription>
          Your changes have been saved successfully.
        </AlertDescription>
      </div>
    </Alert>
  );
}
```

### Warning

```tsx
import { AlertTriangle } from "lucide-react";
import { Alert, AlertTitle, AlertDescription } from "@/components/ui/alert";

export default function AlertWarning() {
  return (
    <Alert variant="warning">
      <AlertTriangle />
      <div>
        <AlertTitle>Warning</AlertTitle>
        <AlertDescription>
          Your account is approaching its usage limit.
        </AlertDescription>
      </div>
    </Alert>
  );
}
```

## Styling

### Data Slots

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

| Slot name           | Element              |
| ------------------- | -------------------- |
| `alert`             | Root `<div>` wrapper |
| `alert-title`       | Title `<h5>`         |
| `alert-description` | Description `<div>`  |

### Customization Examples

```css
/* Make all alerts have a thicker left border */
[data-slot="alert"] {
  @apply border-l-4;
}
```

```tsx
{
  /* Override styles via className */
}
<Alert className="border-l-4">
  <AlertTitle>Note</AlertTitle>
  <AlertDescription>With left accent border.</AlertDescription>
</Alert>;
```

## API Reference

### Alert

The root container with variant styles and `role="alert"`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "destructive" \| "success" \| "warning"` | `"default"` | Visual style variant. |
| `className` | `string` | - | Additional CSS classes. |
| `children` | `React.ReactNode` | - | Alert content (icon, title, description). |

Extends `React.ComponentProps<"div">`. All standard div props are forwarded via `...props`.

### AlertTitle

Heading for the alert message.

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

Extends `React.ComponentProps<"h5">`. All standard h5 props are forwarded via `...props`.

### AlertDescription

Supporting text rendered below the title.

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

Extends `React.ComponentProps<"div">`. All standard div props are forwarded via `...props`.

### alertVariants

A `cva` helper exported for use outside of the `<Alert>` component.

## Accessibility

### Keyboard Interactions

Alert is a non-interactive presentational element and does not have keyboard interactions.

### ARIA Attributes

- Alert renders with `role="alert"`, which causes screen readers to announce the content when it appears.
- For non-urgent notifications, consider using `role="status"` instead.

## Full Component Source

```tsx
"use client";

export {
  Alert,
  AlertTitle,
  AlertDescription,
  alertVariants,
} from "@prototyperco/ui/components/alert";
```
</component>

<component name="alert-dialog" url="https://prototyper-ui.com/docs/components/alert-dialog">
# Alert Dialog
> A modal dialog for confirmations that requires explicit user action
URL: https://prototyper-ui.com/docs/components/alert-dialog
Base UI reference: https://base-ui.com/react/components/alert-dialog
```tsx
import { Button } from "@/components/ui/button";
import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogTitle,
  AlertDialogTrigger,
} from "@/components/ui/alert-dialog";

export default function AlertDialogDemo() {
  return (
    <AlertDialog>
      <AlertDialogTrigger render={<Button variant="outline" />}>
        Discard draft...
      </AlertDialogTrigger>
      <AlertDialogContent>
        <AlertDialogHeader>
          <AlertDialogTitle>Discard draft?</AlertDialogTitle>
          <AlertDialogDescription>
            Your unsaved changes will be lost. This action cannot be undone.
          </AlertDialogDescription>
        </AlertDialogHeader>
        <AlertDialogFooter>
          <AlertDialogCancel>Cancel</AlertDialogCancel>
          <AlertDialogAction>Discard</AlertDialogAction>
        </AlertDialogFooter>
      </AlertDialogContent>
    </AlertDialog>
  );
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/alert-dialog.tsx`

## Usage

```tsx
import {
  AlertDialog,
  AlertDialogTrigger,
  AlertDialogContent,
  AlertDialogHeader,
  AlertDialogTitle,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogAction,
  AlertDialogCancel,
} from "@/components/ui/alert-dialog";

<AlertDialog>
  <AlertDialogTrigger>Delete...</AlertDialogTrigger>
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogTitle>Are you sure?</AlertDialogTitle>
      <AlertDialogDescription>
        This action cannot be undone.
      </AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogCancel>Cancel</AlertDialogCancel>
      <AlertDialogAction>Confirm</AlertDialogAction>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>;
```

## Anatomy

```tsx
<AlertDialog>
  <AlertDialogTrigger />
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogMedia />
      <AlertDialogTitle />
      <AlertDialogDescription />
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogCancel />
      <AlertDialogAction />
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>
```

| Sub-component              | `data-slot`                | Purpose                                                 | Required |
| -------------------------- | -------------------------- | ------------------------------------------------------- | -------- |
| `AlertDialog`              | `alert-dialog`             | Root provider, manages open/close state                 | Yes      |
| `AlertDialogTrigger`       | `alert-dialog-trigger`     | Button that opens the alert dialog                      | Yes      |
| `AlertDialogContent`       | `alert-dialog-content`     | The alert dialog popup panel                            | Yes      |
| `AlertDialogHeader`        | `alert-dialog-header`      | Container for media, title, and description             | No       |
| ↳ `AlertDialogMedia`       | `alert-dialog-media`       | Icon or illustration container (child of Header)        | No       |
| ↳ `AlertDialogTitle`       | `alert-dialog-title`       | Accessible title for the alert dialog (child of Header) | Yes      |
| ↳ `AlertDialogDescription` | `alert-dialog-description` | Accessible description (child of Header)                | No       |
| `AlertDialogFooter`        | `alert-dialog-footer`      | Container for action buttons                            | No       |
| ↳ `AlertDialogCancel`      | `alert-dialog-cancel`      | Cancel button (closes the dialog)                       | No       |
| ↳ `AlertDialogAction`      | `alert-dialog-action`      | Confirm button (does not auto-close)                    | No       |
| `AlertDialogPortal`        | `alert-dialog-portal`      | Renders children into a portal                          | No       |
| `AlertDialogOverlay`       | `alert-dialog-overlay`     | Backdrop behind the alert dialog                        | No       |

## Examples

### Destructive

Use the `variant="destructive"` prop on `AlertDialogAction` to indicate a dangerous action.

```tsx
import { Button } from "@/components/ui/button";
import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogTitle,
  AlertDialogTrigger,
} from "@/components/ui/alert-dialog";

export default function AlertDialogDestructive() {
  return (
    <AlertDialog>
      <AlertDialogTrigger render={<Button variant="outline" />}>
        Delete account...
      </AlertDialogTrigger>
      <AlertDialogContent>
        <AlertDialogHeader>
          <AlertDialogTitle>Delete account</AlertDialogTitle>
          <AlertDialogDescription>
            This will permanently delete your account and all associated data.
            This action cannot be undone.
          </AlertDialogDescription>
        </AlertDialogHeader>
        <AlertDialogFooter>
          <AlertDialogCancel>Cancel</AlertDialogCancel>
          <AlertDialogAction variant="destructive">Delete</AlertDialogAction>
        </AlertDialogFooter>
      </AlertDialogContent>
    </AlertDialog>
  );
}
```

## Styling

### Data Slots

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

| Slot name                  | Element                                 |
| -------------------------- | --------------------------------------- |
| `alert-dialog`             | Root provider (no DOM element rendered) |
| `alert-dialog-trigger`     | The trigger button                      |
| `alert-dialog-portal`      | Portal wrapper                          |
| `alert-dialog-overlay`     | Backdrop overlay                        |
| `alert-dialog-content`     | The popup panel                         |
| `alert-dialog-header`      | Header container (title + description)  |
| `alert-dialog-media`       | Icon or illustration container          |
| `alert-dialog-title`       | Title heading                           |
| `alert-dialog-description` | Description paragraph                   |
| `alert-dialog-footer`      | Footer container (action buttons)       |
| `alert-dialog-action`      | Confirm action button                   |
| `alert-dialog-cancel`      | Cancel button                           |

### Customization Examples

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

/* Wider alert dialog */
[data-slot="alert-dialog-content"] {
  @apply sm:max-w-lg;
}
```

```tsx
{
  /* Use the small size variant */
}
<AlertDialogContent size="sm">{/* ... */}</AlertDialogContent>;
```

## API Reference

### AlertDialog

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 AlertDialog.Root props](https://base-ui.com/react/components/alert-dialog) are forwarded via `...props`.

### AlertDialogTrigger

Button that opens the alert dialog when clicked.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| function` | - | Allows replacing or composing the trigger element with a different component |
| `className` | `string` | - | Additional CSS classes |
| `style` | `CSSProperties \| function` | - | Inline styles or a function that returns styles based on component state |

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

### AlertDialogContent

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

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"default" \| "sm"` | `"default"` | Size variant of the alert dialog |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Alert dialog content |

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

### AlertDialogHeader

Container for media, title, and description. Layout adjusts based on the `size` prop on `AlertDialogContent`.

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

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

### AlertDialogMedia

Container for an icon or illustration displayed in the header.

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

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

### AlertDialogFooter

Container for action buttons. Uses a two-column grid at the `sm` size, and a row layout at `default`.

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

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

### AlertDialogTitle

Accessible title for the alert dialog, rendered as a heading.

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

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

### AlertDialogDescription

Accessible description rendered below the title.

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

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

### AlertDialogAction

Confirm action button. Accepts all `Button` props including `variant` and `size`.

| 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 |
| `className` | `string` | - | Additional CSS classes |

All `Button` props are forwarded via `...props`.

### AlertDialogCancel

Cancel button that closes the alert dialog when clicked. Renders as a `Button` with `variant="outline"` by default.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "destructive" \| "outline" \| "secondary" \| "ghost" \| "link"` | `"outline"` | Visual style variant |
| `size` | `"default" \| "xs" \| "sm" \| "lg" \| "icon" \| "icon-xs" \| "icon-sm" \| "icon-lg"` | `"default"` | Size of the button |
| `className` | `string` | - | Additional CSS classes |

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

### AlertDialogOverlay

Backdrop overlay behind the alert dialog.

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

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

### AlertDialogPortal

Renders children into a React portal.

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

## Accessibility

Unlike a regular Dialog, an Alert Dialog is intended for confirmations and destructive actions. It does not close when clicking outside or pressing `Escape` by default, ensuring the user must make an explicit choice.

### Keyboard Interactions

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

### ARIA Attributes

- `AlertDialogContent` receives `role="alertdialog"`.
- `aria-modal="true"` is set automatically.
- `aria-labelledby` is automatically linked to `AlertDialogTitle`.
- `aria-describedby` is automatically linked to `AlertDialogDescription`.
- Focus is trapped inside the alert dialog while it is open.
- Focus returns to the trigger element when the alert dialog closes.

## Full Component Source

```tsx
"use client";

export {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogMedia,
  AlertDialogOverlay,
  AlertDialogPortal,
  AlertDialogTitle,
  AlertDialogTrigger,
} from "@prototyperco/ui/components/alert-dialog";
```
</component>

<component name="autocomplete" url="https://prototyper-ui.com/docs/components/autocomplete">
# Autocomplete
> text input with suggestions and free-form input capability
URL: https://prototyper-ui.com/docs/components/autocomplete
Base UI reference: https://base-ui.com/react/components/autocomplete
```tsx
"use client";

import {
  Autocomplete,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteInput,
  AutocompleteItem,
  AutocompleteList,
} from "@/components/ui/autocomplete";

const cities = [
  "New York",
  "Los Angeles",
  "Chicago",
  "Houston",
  "Phoenix",
  "Philadelphia",
  "San Antonio",
  "San Diego",
  "Dallas",
  "Austin",
];

export default function AutocompleteDemo() {
  return (
    <Autocomplete items={cities}>
      <AutocompleteInput placeholder="Search a city..." />
      <AutocompleteContent>
        <AutocompleteEmpty>No cities found.</AutocompleteEmpty>
        <AutocompleteList>
          {(item) => (
            <AutocompleteItem key={item} value={item}>
              {item}
            </AutocompleteItem>
          )}
        </AutocompleteList>
      </AutocompleteContent>
    </Autocomplete>
  );
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/autocomplete.tsx`

## Usage

```tsx
import {
  Autocomplete,
  AutocompleteInput,
  AutocompleteContent,
  AutocompleteList,
  AutocompleteItem,
  AutocompleteEmpty,
} from "@/components/ui/autocomplete";

<Autocomplete items={items}>
  <AutocompleteInput placeholder="Search..." />
  <AutocompleteContent>
    <AutocompleteEmpty>No results found.</AutocompleteEmpty>
    <AutocompleteList>
      {(item) => (
        <AutocompleteItem key={item} value={item}>
          {item}
        </AutocompleteItem>
      )}
    </AutocompleteList>
  </AutocompleteContent>
</Autocomplete>;
```

## Anatomy

```tsx
<Autocomplete>
  <AutocompleteInput />
  <AutocompleteContent>
    <AutocompleteEmpty />
    <AutocompleteGroup>
      <AutocompleteGroupLabel />
      <AutocompleteList>
        <AutocompleteItem />
      </AutocompleteList>
    </AutocompleteGroup>
  </AutocompleteContent>
</Autocomplete>
```

| Sub-component            | `data-slot`                | Purpose                                    | Required |
| ------------------------ | -------------------------- | ------------------------------------------ | -------- |
| `Autocomplete`           | -                          | Root provider, manages state and filtering | Yes      |
| `AutocompleteInput`      | `input-group-control`      | Text input with optional trigger button    | Yes      |
| `AutocompleteTrigger`    | `autocomplete-trigger`     | Button that toggles the popup open/closed  | No       |
| `AutocompleteValue`      | `autocomplete-value`       | Displays the current value                 | No       |
| `AutocompleteContent`    | `autocomplete-content`     | Positioned popup containing the list       | Yes      |
| `AutocompleteList`       | `autocomplete-list`        | Scrollable list of items                   | Yes      |
| `AutocompleteItem`       | `autocomplete-item`        | Individual suggestion option               | Yes      |
| `AutocompleteEmpty`      | `autocomplete-empty`       | Shown when no items match the filter       | No       |
| `AutocompleteGroup`      | `autocomplete-group`       | Groups related items together              | No       |
| `AutocompleteGroupLabel` | `autocomplete-group-label` | Label for a group of items                 | No       |
| `AutocompleteSeparator`  | `autocomplete-separator`   | Visual separator between groups            | No       |
| `AutocompleteIcon`       | `autocomplete-icon`        | Icon element                               | No       |
| `AutocompleteStatus`     | `autocomplete-status`      | Screen-reader-only status message          | No       |
| `AutocompleteArrow`      | `autocomplete-arrow`       | Arrow pointing from popup to trigger       | No       |
| `AutocompleteBackdrop`   | `autocomplete-backdrop`    | Full-screen backdrop behind the popup      | No       |

## Examples

### Modes

```tsx
"use client";

import {
  Autocomplete,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteInput,
  AutocompleteItem,
  AutocompleteList,
} from "@/components/ui/autocomplete";

const languages = [
  "JavaScript",
  "TypeScript",
  "Python",
  "Rust",
  "Go",
  "Java",
  "C++",
  "Ruby",
];

export default function AutocompleteModes() {
  return (
    <div className="flex flex-col gap-4 w-full max-w-sm">
      <Autocomplete items={languages} mode="both">
        <AutocompleteInput placeholder="mode=both (filter + inline)" />
        <AutocompleteContent>
          <AutocompleteEmpty>No results.</AutocompleteEmpty>
          <AutocompleteList>
            {(item) => (
              <AutocompleteItem key={item} value={item}>
                {item}
              </AutocompleteItem>
            )}
          </AutocompleteList>
        </AutocompleteContent>
      </Autocomplete>
      <Autocomplete items={languages} mode="inline">
        <AutocompleteInput placeholder="mode=inline (no filter)" />
        <AutocompleteContent>
          <AutocompleteEmpty>No results.</AutocompleteEmpty>
          <AutocompleteList>
            {(item) => (
              <AutocompleteItem key={item} value={item}>
                {item}
              </AutocompleteItem>
            )}
          </AutocompleteList>
        </AutocompleteContent>
      </Autocomplete>
    </div>
  );
}
```

### Sections

```tsx
"use client";

import {
  Autocomplete,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteGroup,
  AutocompleteGroupLabel,
  AutocompleteInput,
  AutocompleteItem,
  AutocompleteList,
} from "@/components/ui/autocomplete";

const items = [
  {
    value: "frontend",
    items: ["React", "Vue", "Svelte", "Angular", "Solid"],
  },
  {
    value: "backend",
    items: ["Node.js", "Django", "Rails", "Spring", "FastAPI"],
  },
];

export default function AutocompleteSections() {
  return (
    <Autocomplete items={items}>
      <AutocompleteInput placeholder="Search frameworks..." />
      <AutocompleteContent>
        <AutocompleteEmpty>No results found.</AutocompleteEmpty>
        <AutocompleteList>
          {(group) => (
            <AutocompleteGroup key={group.value}>
              <AutocompleteGroupLabel>
                {group.value === "frontend" ? "Frontend" : "Backend"}
              </AutocompleteGroupLabel>
              {group.items.map((item: string) => (
                <AutocompleteItem key={item} value={item}>
                  {item}
                </AutocompleteItem>
              ))}
            </AutocompleteGroup>
          )}
        </AutocompleteList>
      </AutocompleteContent>
    </Autocomplete>
  );
}
```

### Disabled

```tsx
import {
  Autocomplete,
  AutocompleteContent,
  AutocompleteInput,
  AutocompleteItem,
  AutocompleteList,
} from "@/components/ui/autocomplete";

const items = ["React", "Vue", "Svelte"];

export default function AutocompleteDisabled() {
  return (
    <Autocomplete items={items} disabled>
      <AutocompleteInput placeholder="Disabled autocomplete" />
      <AutocompleteContent>
        <AutocompleteList>
          {(item) => (
            <AutocompleteItem key={item} value={item}>
              {item}
            </AutocompleteItem>
          )}
        </AutocompleteList>
      </AutocompleteContent>
    </Autocomplete>
  );
}
```

### With Trigger

```tsx
"use client";

import {
  Autocomplete,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteInput,
  AutocompleteItem,
  AutocompleteList,
} from "@/components/ui/autocomplete";

const colors = ["Red", "Orange", "Yellow", "Green", "Blue", "Indigo", "Violet"];

export default function AutocompleteTrigger() {
  return (
    <Autocomplete items={colors}>
      <AutocompleteInput placeholder="Search colors..." showTrigger />
      <AutocompleteContent>
        <AutocompleteEmpty>No colors found.</AutocompleteEmpty>
        <AutocompleteList>
          {(item) => (
            <AutocompleteItem key={item} value={item}>
              {item}
            </AutocompleteItem>
          )}
        </AutocompleteList>
      </AutocompleteContent>
    </Autocomplete>
  );
}
```

## Autocomplete vs Combobox

| Feature              | Autocomplete                           | Combobox                      |
| -------------------- | -------------------------------------- | ----------------------------- |
| Free-form text input | Yes                                    | No (must select an item)      |
| Selection tracking   | No                                     | Yes (`value`/`onValueChange`) |
| Multi-select / chips | No                                     | Yes                           |
| Item check indicator | No                                     | Yes                           |
| Trigger button       | Optional (`showTrigger`)               | Default                       |
| `mode` prop          | Yes (`list`, `both`, `inline`, `none`) | No                            |

## Styling

### Data Slots

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

| Slot name                  | Element                                |
| -------------------------- | -------------------------------------- |
| `input-group-control`      | The text input element                 |
| `autocomplete-trigger`     | Dropdown trigger button                |
| `autocomplete-content`     | Positioned popup panel                 |
| `autocomplete-list`        | Scrollable list container              |
| `autocomplete-item`        | Individual suggestion                  |
| `autocomplete-empty`       | Empty state message                    |
| `autocomplete-group`       | Group container                        |
| `autocomplete-group-label` | Group label                            |
| `autocomplete-separator`   | Separator line between groups          |
| `autocomplete-value`       | Value display                          |
| `autocomplete-icon`        | Icon element                           |
| `autocomplete-status`      | Screen-reader status (visually hidden) |
| `autocomplete-arrow`       | Popup arrow                            |
| `autocomplete-backdrop`    | Full-screen backdrop                   |

### Customization Examples

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

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

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

## API Reference

### Autocomplete

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

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `T[]` | - | Array of items to filter through |
| `mode` | `"list" \| "both" \| "inline" \| "none"` | `"list"` | How the autocomplete behaves: list (filter only), both (filter + inline), inline (inline only), none (no filtering) |
| `value` | `string` | - | Controlled input value |
| `defaultValue` | `string` | - | Initial input value for uncontrolled usage |
| `onValueChange` | `(value: string, eventDetails: ChangeEventDetails) => void` | - | Callback when the input value changes |
| `autoHighlight` | `boolean \| "always"` | `false` | Whether the first matching item is highlighted automatically |
| `openOnInputClick` | `boolean` | `false` | Whether the popup opens when clicking the input |
| `submitOnItemClick` | `boolean` | `false` | Whether clicking an item should submit the owning form |
| `disabled` | `boolean` | `false` | Whether the autocomplete is disabled |

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

### AutocompleteInput

Text input with optional trigger button, wrapped in an `InputGroup`.

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

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

### AutocompleteTrigger

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 Autocomplete.Trigger props](https://base-ui.com/react/components/autocomplete) are forwarded via `...props`.

### AutocompleteValue

Displays the current input value.

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

### AutocompleteContent

Positioned popup that contains the list. Wraps `Autocomplete.Portal`, `Autocomplete.Positioner`, and `Autocomplete.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` | `AutocompletePrimitive.Positioner.Props["anchor"]` | - | Custom anchor element |
| `className` | `string` | - | Additional CSS classes |

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

### AutocompleteList

Scrollable list container for autocomplete items.

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

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

### AutocompleteItem

Individual suggestion option. Unlike `ComboboxItem`, does not include a check-mark indicator.

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

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

### AutocompleteEmpty

Message shown when no items match the current filter.

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

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

### AutocompleteGroup

Groups related autocomplete items together.

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

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

### AutocompleteGroupLabel

Label for a group of items.

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

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

### AutocompleteSeparator

Visual separator between groups.

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

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

### AutocompleteIcon

Icon element within the autocomplete.

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

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

### AutocompleteStatus

Screen-reader-only status message that announces changes.

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

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

### AutocompleteArrow

Arrow element pointing from the popup to the trigger.

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

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

### AutocompleteBackdrop

Full-screen backdrop rendered behind the popup.

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

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

### AutocompleteCollection

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

### useAutocompleteFilter

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

## 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`     | Accepts the highlighted item's value into the input       |
| `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      |

### ARIA Attributes

- The input has `role="combobox"` with `aria-expanded` indicating popup state.
- `aria-activedescendant` tracks the currently highlighted item.
- `aria-autocomplete` reflects the `mode` prop behavior.
- `AutocompleteContent` has `role="listbox"` for the list of suggestions.
- `AutocompleteItem` has `role="option"` with `aria-disabled` for disabled items.
- `AutocompleteGroup` uses `role="group"` with `aria-labelledby` linked to the group label.
- `AutocompleteStatus` provides a live region for screen reader announcements.

## Full Component Source

```tsx
"use client";

export {
  Autocomplete,
  AutocompleteCollection,
  AutocompleteInput,
  AutocompleteContent,
  AutocompleteList,
  AutocompleteItem,
  AutocompleteEmpty,
  AutocompleteGroup,
  AutocompleteGroupLabel,
  AutocompleteSeparator,
  AutocompleteTrigger,
  AutocompleteValue,
  AutocompleteIcon,
  AutocompleteStatus,
  AutocompleteArrow,
  AutocompleteBackdrop,
  useAutocompleteFilter,
} from "@prototyperco/ui/components/autocomplete";
```
</component>

<component name="avatar" url="https://prototyper-ui.com/docs/components/avatar">
# Avatar
> visual representation of a user with image and fallback support
URL: https://prototyper-ui.com/docs/components/avatar
Base UI reference: https://base-ui.com/react/components/avatar
```tsx
import { Avatar, AvatarImage, AvatarFallback } from "@/components/ui/avatar";

export default function AvatarDemo() {
  return (
    <Avatar>
      <AvatarImage
        src="https://pbs.twimg.com/profile_images/1940685845033295872/2Wo-jYaN_400x400.jpg"
        alt="@prototyper"
      />
      <AvatarFallback>CN</AvatarFallback>
    </Avatar>
  );
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/avatar.tsx`

## Usage

```tsx
import { Avatar, AvatarImage, AvatarFallback } from "@/components/ui/avatar";

<Avatar>
  <AvatarImage src="/avatar.png" alt="User" />
  <AvatarFallback>AB</AvatarFallback>
</Avatar>;
```

## Examples

### Fallback

```tsx
import { Avatar, AvatarFallback } from "@/components/ui/avatar";

export default function AvatarFallbackDemo() {
  return (
    <Avatar>
      <AvatarFallback>AB</AvatarFallback>
    </Avatar>
  );
}
```

## Styling

### Data Slots

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

| Slot name            | Element                             |
| -------------------- | ----------------------------------- |
| `avatar`             | Root container                      |
| `avatar-image`       | The `<img>` element                 |
| `avatar-fallback`    | Fallback content (initials or icon) |
| `avatar-badge`       | Status badge indicator              |
| `avatar-group`       | Group wrapper for multiple avatars  |
| `avatar-group-count` | Overflow count element in a group   |

### Customization Examples

```css
/* Make all avatars larger */
[data-slot="avatar"] {
  @apply size-12 rounded-lg after:rounded-lg;
}

/* Custom fallback color */
[data-slot="avatar-fallback"] {
  @apply bg-primary text-primary-foreground;
}
```

```tsx
{
  /* Override styles via className */
}
<Avatar className="size-12 rounded-lg after:rounded-lg">
  <AvatarImage src="/avatar.png" alt="User" />
  <AvatarFallback className="rounded-lg">AB</AvatarFallback>
</Avatar>;
```

## API Reference

### Avatar

Root component that wraps the avatar image and fallback. Supports three sizes via the `size` prop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"default" \| "sm" \| "lg"` | `"default"` | Size of the avatar (sm: 24px, default: 32px, lg: 40px) |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Avatar content (image, fallback, badge) |

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

### AvatarImage

Displays the user's image. Automatically hidden when the image fails to load.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | `string` | - | Image source URL |
| `alt` | `string` | - | Accessible alt text for the image |
| `className` | `string` | - | Additional CSS classes |

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

### AvatarFallback

Displayed when no image is provided or while the image is loading. Typically renders initials or an icon.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Fallback content (initials, icon, etc.) |

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

### AvatarBadge

A small status indicator positioned at the bottom-right corner of the avatar. Size adapts to the parent avatar's size.

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

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

### AvatarGroup

Wraps multiple avatars in an overlapping horizontal stack.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Avatar components to stack |

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

### AvatarGroupCount

Displays the count of remaining avatars that are not shown in the group.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Count content (e.g. "+3") |

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

## Accessibility

### ARIA Attributes

- The `AvatarImage` renders a standard `<img>` element. Always provide a descriptive `alt` attribute for screen readers.
- When no image is available, `AvatarFallback` content (initials or icon) serves as the visual representation. Ensure the fallback is meaningful.
- `AvatarBadge` is decorative by default. Add `aria-label` if the badge conveys important status information.
- `AvatarGroup` uses standard `div` semantics. Consider adding `role="group"` and `aria-label` for groups of avatars.

## Compose

This component is available in [`@prototyperco/compose`](/docs/compose).

### Catalog Definition

```typescript title="avatar.catalog.ts"
import { z } from "zod";
import { defineComponent } from "@prototyperco/compose/catalog";

export default defineComponent({
  description: "A circular avatar displaying a user image or fallback initials",
  props: z.object({
    src: z.string().optional().describe("URL of the avatar image"),
    fallback: z
      .string()
      .describe(
        "Fallback text shown when image is unavailable (typically initials)",
      ),
    alt: z.string().optional().describe("Alt text for the avatar image"),
    size: z.enum(["sm", "default", "lg"]).optional().describe("Avatar size"),
  }),
  events: [],
  example: { fallback: "JD", size: "default" },
});
```

### Example Spec

```json
{
  "root": "avatar",
  "elements": {
    "avatar": {
      "type": "Avatar",
      "props": {
        "fallback": "JD",
        "size": "default"
      }
    }
  }
}
```

Learn more in the [Compose documentation](/docs/compose).

## Full Component Source

```tsx
"use client";

export {
  Avatar,
  AvatarImage,
  AvatarFallback,
  AvatarGroup,
  AvatarGroupCount,
  AvatarBadge,
} from "@prototyperco/ui/components/avatar";
```
</component>

<component name="badge" url="https://prototyper-ui.com/docs/components/badge">
# Badge
> A small status indicator with color variants
URL: https://prototyper-ui.com/docs/components/badge
```tsx
import { Badge } from "@/components/ui/badge";

export default function BadgeDemo() {
  return <Badge>Badge</Badge>;
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/badge.tsx`

## Usage

```tsx
import { Badge } from "@/components/ui/badge";

<Badge>Badge</Badge>;
```

## Examples

### Secondary

```tsx
import { Badge } from "@/components/ui/badge";

export default function BadgeSecondary() {
  return <Badge variant="secondary">Secondary</Badge>;
}
```

### Destructive

```tsx
import { Badge } from "@/components/ui/badge";

export default function BadgeDestructive() {
  return <Badge variant="destructive">Destructive</Badge>;
}
```

### Outline

```tsx
import { Badge } from "@/components/ui/badge";

export default function BadgeOutline() {
  return <Badge variant="outline">Outline</Badge>;
}
```

### Success

```tsx
import { Badge } from "@/components/ui/badge";

export default function BadgeSuccess() {
  return <Badge variant="success">Success</Badge>;
}
```

### Warning

```tsx
import { Badge } from "@/components/ui/badge";

export default function BadgeWarning() {
  return <Badge variant="warning">Warning</Badge>;
}
```

## Styling

### Data Slots

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

| Slot name | Element           |
| --------- | ----------------- |
| `badge`   | The `<span>` root |

### Customization Examples

```css
/* Make all badges square */
[data-slot="badge"] {
  @apply rounded-md;
}
```

```tsx
{
  /* Use className for one-off overrides */
}
<Badge className="rounded-md px-4">Custom</Badge>;
```

## API Reference

### Badge

A small inline status indicator.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "secondary" \| "destructive" \| "outline" \| "success" \| "warning"` | `"default"` | Visual style variant. |
| `className` | `string` | - | Additional CSS classes. |
| `children` | `React.ReactNode` | - | Badge content. |

Extends `React.ComponentProps<"span">`. All standard span props are forwarded via `...props`.

### badgeVariants

A `cva` helper exported for use outside of the `<Badge>` component:

```tsx
import { badgeVariants } from "@/components/ui/badge";

<span className={badgeVariants({ variant: "success" })}>Active</span>;
```

## Accessibility

### Keyboard Interactions

Badge is a non-interactive presentational element and does not have keyboard interactions.

### ARIA Attributes

- Badge renders as a `<span>` with no implicit ARIA role.
- For status indicators, consider adding `role="status"` and an appropriate `aria-label`.

## Full Component Source

```tsx
"use client";

export { Badge, badgeVariants } from "@prototyperco/ui/components/badge";
```
</component>

<component name="breadcrumb" url="https://prototyper-ui.com/docs/components/breadcrumb">
# Breadcrumb
> A navigation trail showing the current page location
URL: https://prototyper-ui.com/docs/components/breadcrumb
```tsx
import {
  Breadcrumb,
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbSeparator,
  BreadcrumbPage,
} from "@/components/ui/breadcrumb";

export default function BreadcrumbDemo() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="/">Home</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink href="/docs">Docs</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  );
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/breadcrumb.tsx`

## Usage

```tsx
import {
  Breadcrumb,
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbSeparator,
  BreadcrumbPage,
} from "@/components/ui/breadcrumb";

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="/">Home</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>Current Page</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>;
```

## Anatomy

```tsx
<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink />
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbEllipsis />
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage />
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>
```

| Sub-component         | `data-slot`            | Purpose                                  | Required |
| --------------------- | ---------------------- | ---------------------------------------- | -------- |
| `Breadcrumb`          | `breadcrumb`           | Root `<nav>` with aria-label             | Yes      |
| `BreadcrumbList`      | `breadcrumb-list`      | Ordered list of breadcrumb items         | Yes      |
| `BreadcrumbItem`      | `breadcrumb-item`      | Individual breadcrumb entry              | Yes      |
| `BreadcrumbLink`      | `breadcrumb-link`      | Clickable navigation link                | No       |
| `BreadcrumbPage`      | `breadcrumb-page`      | Current page indicator (non-interactive) | No       |
| `BreadcrumbSeparator` | `breadcrumb-separator` | Visual separator between items           | No       |
| `BreadcrumbEllipsis`  | `breadcrumb-ellipsis`  | Collapsed items indicator                | No       |

## Examples

### With Ellipsis

```tsx
import {
  Breadcrumb,
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbSeparator,
  BreadcrumbEllipsis,
  BreadcrumbPage,
} from "@/components/ui/breadcrumb";

export default function BreadcrumbWithEllipsis() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="/">Home</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbEllipsis />
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink href="/docs/components">Components</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  );
}
```

## Styling

### Data Slots

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

| Slot name              | Element                     |
| ---------------------- | --------------------------- |
| `breadcrumb`           | Root `<nav>` wrapper        |
| `breadcrumb-list`      | The `<ol>` list             |
| `breadcrumb-item`      | Each `<li>` item            |
| `breadcrumb-link`      | Clickable `<a>` link        |
| `breadcrumb-page`      | Current page `<span>`       |
| `breadcrumb-separator` | Separator `<li>`            |
| `breadcrumb-ellipsis`  | Ellipsis indicator `<span>` |

### Customization Examples

```css
/* Change separator color */
[data-slot="breadcrumb-separator"] {
  @apply text-foreground;
}
```

```tsx
{
  /* Custom separator character */
}
<BreadcrumbSeparator>/</BreadcrumbSeparator>;
```

## API Reference

### Breadcrumb

Root navigation element with `aria-label="breadcrumb"`.

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

Extends `React.ComponentProps<"nav">`. All standard nav props are forwarded via `...props`.

### BreadcrumbList

Ordered list container for breadcrumb items.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes. |
| `children` | `React.ReactNode` | - | BreadcrumbItem and BreadcrumbSeparator elements. |

Extends `React.ComponentProps<"ol">`. All standard ol props are forwarded via `...props`.

### BreadcrumbItem

Individual breadcrumb entry wrapping a link or page indicator.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes. |
| `children` | `React.ReactNode` | - | BreadcrumbLink, BreadcrumbPage, or BreadcrumbEllipsis. |

Extends `React.ComponentProps<"li">`. All standard li props are forwarded via `...props`.

### BreadcrumbLink

Clickable navigation link within a breadcrumb item.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` | - | URL to navigate to. |
| `className` | `string` | - | Additional CSS classes. |
| `children` | `React.ReactNode` | - | Link text. |

Extends `React.ComponentProps<"a">`. All standard anchor props are forwarded via `...props`.

### BreadcrumbPage

Current page indicator rendered as a non-interactive span.

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

Extends `React.ComponentProps<"span">`. All standard span props are forwarded via `...props`.

### BreadcrumbSeparator

Visual separator between breadcrumb items. Defaults to a chevron icon.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `React.ReactNode` | - | Custom separator content (defaults to ChevronRight icon). |
| `className` | `string` | - | Additional CSS classes. |

Extends `React.ComponentProps<"li">`. All standard li props are forwarded via `...props`.

### BreadcrumbEllipsis

Collapsed items indicator showing a "more" icon.

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

Extends `React.ComponentProps<"span">`. All standard span props are forwarded via `...props`.

## Accessibility

### Keyboard Interactions

| Key   | Action                               |
| ----- | ------------------------------------ |
| `Tab` | Moves focus between breadcrumb links |

### ARIA Attributes

- `Breadcrumb` renders as a `<nav>` with `aria-label="breadcrumb"`.
- `BreadcrumbPage` has `aria-current="page"` to indicate the current location.
- `BreadcrumbSeparator` has `aria-hidden="true"` to hide decorative separators from screen readers.

## Full Component Source

```tsx
"use client";

export {
  Breadcrumb,
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbPage,
  BreadcrumbSeparator,
  BreadcrumbEllipsis,
} from "@prototyperco/ui/components/breadcrumb";
```
</component>

<component name="button" url="https://prototyper-ui.com/docs/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>;
}
```

### Primary Soft

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

export default function ButtonPrimarySoft() {
  return <Button variant="primary-soft">Primary Soft</Button>;
}
```

### Destructive Soft

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

export default function ButtonDestructiveSoft() {
  return <Button variant="destructive-soft">Destructive Soft</Button>;
}
```

### Success

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

export default function ButtonSuccess() {
  return <Button variant="success">Success</Button>;
}
```

### Warning

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

export default function ButtonWarning() {
  return <Button variant="warning">Warning</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" \| "primary-soft" \| "destructive-soft" \| "success" \| "warning" \| "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.

## Compose

This component is available in [`@prototyperco/compose`](/docs/compose).

## Full Component Source

```tsx
"use client";

export { Button, buttonVariants } from "@prototyperco/ui/components/button";
```
</component>

<component name="card" url="https://prototyper-ui.com/docs/components/card">
# Card
> a surface container with variants for grouping content
URL: https://prototyper-ui.com/docs/components/card
```tsx
import {
  Card,
  CardHeader,
  CardTitle,
  CardDescription,
  CardContent,
  CardFooter,
} from "@/components/ui/card";
import { Button } from "@/components/ui/button";

export default function CardDemo() {
  return (
    <Card className="w-[350px]">
      <CardHeader>
        <CardTitle>Create project</CardTitle>
        <CardDescription>Deploy your new project in one click.</CardDescription>
      </CardHeader>
      <CardContent>
        <p className="text-sm text-muted-foreground">
          Your project will be deployed to a production environment with
          automatic scaling and monitoring enabled.
        </p>
      </CardContent>
      <CardFooter>
        <Button variant="outline" size="sm">
          Cancel
        </Button>
        <Button size="sm">Deploy</Button>
      </CardFooter>
    </Card>
  );
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/card.tsx`

## Usage

```tsx
import {
  Card,
  CardHeader,
  CardTitle,
  CardDescription,
  CardContent,
  CardFooter,
} from "@/components/ui/card";
```

```tsx
<Card>
  <CardHeader>
    <CardTitle>Title</CardTitle>
    <CardDescription>Description</CardDescription>
  </CardHeader>
  <CardContent>Content</CardContent>
  <CardFooter>Footer</CardFooter>
</Card>
```

## Anatomy

```tsx
<Card>
  <CardHeader>
    <CardTitle />
    <CardDescription />
  </CardHeader>
  <CardContent />
  <CardFooter />
</Card>
```

| Sub-component     | `data-slot`        | Purpose                               | Required |
| ----------------- | ------------------ | ------------------------------------- | -------- |
| `Card`            | `card`             | Root container with surface variants  | Yes      |
| `CardHeader`      | `card-header`      | Flex column for title and description | No       |
| `CardTitle`       | `card-title`       | Heading for the card                  | No       |
| `CardDescription` | `card-description` | Supporting text below the title       | No       |
| `CardContent`     | `card-content`     | Main content area with flex-1 growth  | No       |
| `CardFooter`      | `card-footer`      | Horizontal flex container for actions | No       |

## Examples

### Elevated

```tsx
import {
  Card,
  CardHeader,
  CardTitle,
  CardDescription,
  CardContent,
} from "@/components/ui/card";

export default function CardElevated() {
  return (
    <Card variant="elevated" className="w-[350px]">
      <CardHeader>
        <CardTitle>Elevated Card</CardTitle>
        <CardDescription>
          Uses a stronger shadow for more visual prominence.
        </CardDescription>
      </CardHeader>
      <CardContent>
        <p className="text-sm text-muted-foreground">
          The elevated variant is ideal for floating panels, popovers, or
          content that needs to stand out from the page.
        </p>
      </CardContent>
    </Card>
  );
}
```

### Interactive

```tsx
import {
  Card,
  CardHeader,
  CardTitle,
  CardDescription,
} from "@/components/ui/card";

export default function CardInteractive() {
  return (
    <div className="flex gap-4">
      <Card interactive className="w-[200px]">
        <CardHeader>
          <CardTitle>Starter</CardTitle>
          <CardDescription>Free forever</CardDescription>
        </CardHeader>
      </Card>
      <Card interactive variant="elevated" className="w-[200px]">
        <CardHeader>
          <CardTitle>Pro</CardTitle>
          <CardDescription>$9/month</CardDescription>
        </CardHeader>
      </Card>
    </div>
  );
}
```

### With Form

```tsx
import {
  Card,
  CardHeader,
  CardTitle,
  CardDescription,
  CardContent,
  CardFooter,
} from "@/components/ui/card";
import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/text-field";

export default function CardWithForm() {
  return (
    <Card className="w-[350px]">
      <CardHeader>
        <CardTitle>Sign in</CardTitle>
        <CardDescription>
          Enter your credentials to access your account.
        </CardDescription>
      </CardHeader>
      <CardContent className="space-y-3">
        <div className="space-y-1">
          <label className="text-sm font-medium">Email</label>
          <Input placeholder="you@example.com" />
        </div>
        <div className="space-y-1">
          <label className="text-sm font-medium">Password</label>
          <Input type="password" placeholder="Enter password" />
        </div>
      </CardContent>
      <CardFooter>
        <Button className="w-full">Sign in</Button>
      </CardFooter>
    </Card>
  );
}
```

## Styling

### Data Slots

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

| Slot name          | Element              |
| ------------------ | -------------------- |
| `card`             | Root `<div>` wrapper |
| `card-header`      | Header container     |
| `card-title`       | Title `<h3>`         |
| `card-description` | Description `<p>`    |
| `card-content`     | Content container    |
| `card-footer`      | Footer container     |

### Customization Examples

```css
/* Make all cards have a larger radius */
[data-slot="card"] {
  @apply rounded-2xl;
}

/* Give card titles more weight */
[data-slot="card-title"] {
  @apply text-lg font-bold;
}
```

```tsx
{
  /* Override styles via className */
}
<Card className="rounded-2xl p-6">{/* ... */}</Card>;
```

## API Reference

### Card

The root container with surface-tier variants.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "secondary" \| "tertiary" \| "elevated" \| "transparent"` | `"default"` | Surface variant controlling background, border, and shadow. |
| `interactive` | `boolean` | `false` | Enables hover lift and active press scale effects. |
| `className` | `string` | - | Additional CSS classes. |
| `children` | `React.ReactNode` | - | Card content. |

Extends `React.ComponentProps<"div">`. All standard div props are forwarded via `...props`.

### CardHeader

Flex column container for title and description.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes. |
| `children` | `React.ReactNode` | - | Header content (typically CardTitle and CardDescription). |

Extends `React.ComponentProps<"div">`. All standard div props are forwarded via `...props`.

### CardTitle

Card heading rendered as an `<h3>`.

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

Extends `React.ComponentProps<"h3">`. All standard h3 props are forwarded via `...props`.

### CardDescription

Muted supporting text rendered as a `<p>`.

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

Extends `React.ComponentProps<"p">`. All standard p props are forwarded via `...props`.

### CardContent

Main content area with `flex-1` growth.

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

Extends `React.ComponentProps<"div">`. All standard div props are forwarded via `...props`.

### CardFooter

Horizontal flex container for action buttons.

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

Extends `React.ComponentProps<"div">`. All standard div props are forwarded via `...props`.

### cardVariants

Use `cardVariants` to apply card styles to non-card elements:

```tsx
import { cardVariants } from "@/components/ui/card";

<div className={cardVariants({ variant: "elevated", interactive: true })}>
  Custom card element
</div>;
```

## Accessibility

### Keyboard Interactions

Card is a non-interactive presentational container and does not have keyboard interactions. When the `interactive` prop is set, the card gains a pointer cursor but remains a `<div>` -- wrap it in an `<a>` or `<button>` if it should be keyboard-focusable.

### ARIA Attributes

- Card renders as a plain `<div>` with no implicit ARIA role.
- Use `role="region"` with `aria-label` if the card represents a distinct landmark.
- When used with `interactive`, consider wrapping in an interactive element (`<a>`, `<button>`) for proper keyboard and screen reader support.

## Compose

This component is available in [`@prototyperco/compose`](/docs/compose).

### Catalog Definition

```typescript title="card.catalog.ts"
import { z } from "zod";
import { defineComponent } from "@prototyperco/compose/catalog";

export default defineComponent({
  description:
    "A container card with optional header, content, and footer sections",
  props: z.object({
    title: z.string().optional().describe("Card header title"),
    description: z.string().optional().describe("Card header description"),
    variant: z
      .enum(["default", "secondary", "tertiary", "elevated", "transparent"])
      .optional()
      .describe(
        "Visual style variant controlling background, border, and shadow",
      ),
    interactive: z
      .boolean()
      .optional()
      .describe("When true, adds hover lift and press effects"),
    className: z.string().optional().describe("Additional CSS classes"),
  }),
  slots: ["header", "content", "footer"],
  example: {
    title: "Welcome",
    description: "Get started with your dashboard",
    variant: "default",
  },
});
```

### Example Spec

```json
{
  "root": "card",
  "elements": {
    "card": {
      "type": "Card",
      "props": {
        "title": "Welcome",
        "description": "Get started with your dashboard",
        "variant": "default"
      },
      "children": ["card_content"]
    },
    "card_content": {
      "type": "Text",
      "props": { "content": "Here is your main content area." }
    }
  }
}
```

Learn more in the [Compose documentation](/docs/compose).

## Full Component Source

```tsx
"use client";

export {
  Card,
  CardHeader,
  CardTitle,
  CardDescription,
  CardContent,
  CardFooter,
  cardVariants,
} from "@prototyperco/ui/components/card";
```
</component>

<component name="checkbox" url="https://prototyper-ui.com/docs/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.

## Compose

This component is available in [`@prototyperco/compose`](/docs/compose).

### Catalog Definition

```typescript title="checkbox.catalog.ts"
import { z } from "zod";
import { defineComponent } from "@prototyperco/compose/catalog";

export default defineComponent({
  description: "A checkbox toggle for boolean values",
  props: z.object({
    label: z
      .string()
      .optional()
      .describe("Label displayed next to the checkbox"),
    checked: z.boolean().optional().describe("Whether the checkbox is checked"),
    disabled: z
      .boolean()
      .optional()
      .describe("Whether the checkbox is disabled"),
  }),
  events: ["change"],
  example: { label: "I agree to the terms", checked: false },
});
```

### Example Spec

```json
{
  "root": "check",
  "elements": {
    "check": {
      "type": "Checkbox",
      "props": {
        "label": "I agree to the terms",
        "checked": false
      },
      "$bindState": { "path": "/agreed", "event": "change" }
    }
  }
}
```

Learn more in the [Compose documentation](/docs/compose).

## Full Component Source

```tsx
"use client";

export {
  Checkbox,
  CheckboxControl,
  CheckboxIndicator,
} from "@prototyperco/ui/components/checkbox";
```
</component>

<component name="checkbox-group" url="https://prototyper-ui.com/docs/components/checkbox-group">
# Checkbox Group
> group of checkboxes with shared state and select-all support
URL: https://prototyper-ui.com/docs/components/checkbox-group
Base UI reference: https://base-ui.com/react/components/checkbox-group
```tsx
import {
  Checkbox,
  CheckboxControl,
  CheckboxIndicator,
} from "@/components/ui/checkbox";
import { CheckboxGroup } from "@/components/ui/checkbox-group";

export default function CheckboxGroupDemo() {
  return (
    <CheckboxGroup defaultValue={["react"]}>
      <Checkbox name="react" value="react">
        <CheckboxControl>
          <CheckboxIndicator />
        </CheckboxControl>
        React
      </Checkbox>
      <Checkbox name="vue" value="vue">
        <CheckboxControl>
          <CheckboxIndicator />
        </CheckboxControl>
        Vue
      </Checkbox>
      <Checkbox name="svelte" value="svelte">
        <CheckboxControl>
          <CheckboxIndicator />
        </CheckboxControl>
        Svelte
      </Checkbox>
    </CheckboxGroup>
  );
}
```

## Installation

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

This will add the following files to your project:

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

## Usage

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

<CheckboxGroup defaultValue={["option-1"]}>
  <Checkbox value="option-1">
    <CheckboxControl>
      <CheckboxIndicator />
    </CheckboxControl>
    Option 1
  </Checkbox>
  <Checkbox value="option-2">
    <CheckboxControl>
      <CheckboxIndicator />
    </CheckboxControl>
    Option 2
  </Checkbox>
</CheckboxGroup>;
```

## Anatomy

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

| Sub-component       | `data-slot`          | Purpose                                       | Required |
| ------------------- | -------------------- | --------------------------------------------- | -------- |
| `CheckboxGroup`     | `checkbox-group`     | Root container, manages group state           | Yes      |
| `Checkbox`          | `checkbox`           | Individual checkbox (from checkbox component) | Yes      |
| `CheckboxControl`   | `checkbox-control`   | Visual box (from checkbox component)          | Yes      |
| `CheckboxIndicator` | `checkbox-indicator` | Checkmark icon (from checkbox component)      | Yes      |

## Examples

### Parent (Select All)

```tsx
"use client";

import * as React from "react";

import {
  Checkbox,
  CheckboxControl,
  CheckboxIndicator,
} from "@/components/ui/checkbox";
import { CheckboxGroup } from "@/components/ui/checkbox-group";

const allToppings = ["cheese", "pepperoni", "mushrooms", "olives"];

export default function CheckboxGroupParent() {
  const [value, setValue] = React.useState<string[]>(["cheese", "pepperoni"]);

  return (
    <CheckboxGroup
      value={value}
      onValueChange={setValue}
      allValues={allToppings}
    >
      <Checkbox parent>
        <CheckboxControl>
          <CheckboxIndicator />
        </CheckboxControl>
        Select all toppings
      </Checkbox>
      <div className="ml-6 flex flex-col gap-2">
        <Checkbox value="cheese">
          <CheckboxControl>
            <CheckboxIndicator />
          </CheckboxControl>
          Cheese
        </Checkbox>
        <Checkbox value="pepperoni">
          <CheckboxControl>
            <CheckboxIndicator />
          </CheckboxControl>
          Pepperoni
        </Checkbox>
        <Checkbox value="mushrooms">
          <CheckboxControl>
            <CheckboxIndicator />
          </CheckboxControl>
          Mushrooms
        </Checkbox>
        <Checkbox value="olives">
          <CheckboxControl>
            <CheckboxIndicator />
          </CheckboxControl>
          Olives
        </Checkbox>
      </div>
    </CheckboxGroup>
  );
}
```

### Disabled

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

export default function CheckboxGroupDisabled() {
  return (
    <CheckboxGroup defaultValue={["terms"]} disabled>
      <Checkbox name="terms" value="terms">
        <CheckboxControl>
          <CheckboxIndicator />
        </CheckboxControl>
        Accept terms
      </Checkbox>
      <Checkbox name="privacy" value="privacy">
        <CheckboxControl>
          <CheckboxIndicator />
        </CheckboxControl>
        Accept privacy policy
      </Checkbox>
    </CheckboxGroup>
  );
}
```

### Controlled

```tsx
"use client";

import { useState } from "react";
import {
  Checkbox,
  CheckboxControl,
  CheckboxIndicator,
} from "@/components/ui/checkbox";
import { CheckboxGroup } from "@/components/ui/checkbox-group";

export default function CheckboxGroupControlled() {
  const [value, setValue] = useState<string[]>(["light"]);

  return (
    <div className="flex flex-col gap-4">
      <CheckboxGroup value={value} onValueChange={setValue}>
        <Checkbox name="light" value="light">
          <CheckboxControl>
            <CheckboxIndicator />
          </CheckboxControl>
          Light mode
        </Checkbox>
        <Checkbox name="dark" value="dark">
          <CheckboxControl>
            <CheckboxIndicator />
          </CheckboxControl>
          Dark mode
        </Checkbox>
        <Checkbox name="system" value="system">
          <CheckboxControl>
            <CheckboxIndicator />
          </CheckboxControl>
          System preference
        </Checkbox>
      </CheckboxGroup>
      <p className="text-sm text-muted-foreground">
        Selected: {value.length > 0 ? value.join(", ") : "none"}
      </p>
    </div>
  );
}
```

## Styling

### Data Slots

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

| Slot name        | Element                           |
| ---------------- | --------------------------------- |
| `checkbox-group` | Root container for all checkboxes |

### Customization Examples

```css
/* Horizontal layout */
[data-slot="checkbox-group"] {
  @apply flex-row gap-4;
}
```

```tsx
{
  /* Override layout via className */
}
<CheckboxGroup className="flex-row gap-6">{/* ... */}</CheckboxGroup>;
```

## API Reference

### CheckboxGroup

Root container that manages which checkboxes are checked.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string[]` | - | Controlled array of checked checkbox values |
| `defaultValue` | `string[]` | - | Initial checked values for uncontrolled usage |
| `onValueChange` | `(value: string[], eventDetails: ChangeEventDetails) => void` | - | Callback when the checked values change |
| `allValues` | `string[]` | - | All checkbox values in the group. Required for the parent (select-all) pattern. |
| `disabled` | `boolean` | `false` | Whether all checkboxes in the group are disabled |
| `className` | `string` | - | Additional CSS classes |

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

## Accessibility

### Keyboard Interactions

| Key     | Action                         |
| ------- | ------------------------------ |
| `Space` | Toggles the focused checkbox   |
| `Tab`   | Moves focus between checkboxes |

### ARIA Attributes

- `CheckboxGroup` renders with `role="group"`.
- Each `Checkbox` within renders with `role="checkbox"`.
- `aria-checked` is set to `true`, `false`, or `mixed` (for parent checkbox) based on state.
- `aria-disabled` is set when the group or an individual checkbox is disabled.
- The parent checkbox shows `mixed` state when some but not all children are checked.

## Full Component Source

```tsx
"use client";

export { CheckboxGroup } from "@prototyperco/ui/components/checkbox-group";
```
</component>

<component name="collapsible" url="https://prototyper-ui.com/docs/components/collapsible">
# Collapsible
> a collapsible section for revealing or hiding content
URL: https://prototyper-ui.com/docs/components/collapsible
Base UI reference: https://base-ui.com/react/components/collapsible
```tsx
"use client";

import { ChevronsUpDown } from "lucide-react";

import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
} from "@/components/ui/collapsible";

export default function CollapsibleDemo() {
  return (
    <Collapsible className="w-[340px] space-y-2">
      <div className="flex items-center justify-between gap-4">
        <h4 className="text-sm font-semibold">3 items tagged</h4>
        <CollapsibleTrigger className="inline-flex size-9 items-center justify-center rounded-md border border-border bg-transparent hover-only:hover:bg-surface-secondary">
          <ChevronsUpDown className="size-4" />
          <span className="sr-only">Toggle</span>
        </CollapsibleTrigger>
      </div>
      <div className="rounded-md border border-border px-4 py-3 text-sm">
        @prototyperco/ui
      </div>
      <CollapsibleContent className="space-y-2">
        <div className="rounded-md border border-border px-4 py-3 text-sm">
          @prototyperco/cli
        </div>
        <div className="rounded-md border border-border px-4 py-3 text-sm">
          @prototyperco/mcp
        </div>
      </CollapsibleContent>
    </Collapsible>
  );
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/collapsible.tsx`

## Usage

```tsx
import {
  Collapsible,
  CollapsibleTrigger,
  CollapsibleContent,
} from "@/components/ui/collapsible";

<Collapsible>
  <CollapsibleTrigger>Toggle</CollapsibleTrigger>
  <CollapsibleContent>
    Content that can be collapsed or expanded.
  </CollapsibleContent>
</Collapsible>;
```

## Anatomy

```tsx
<Collapsible>
  <CollapsibleTrigger />
  <CollapsibleContent>{/* your content */}</CollapsibleContent>
</Collapsible>
```

| Sub-component        | `data-slot`           | Purpose                                   | Required |
| -------------------- | --------------------- | ----------------------------------------- | -------- |
| `Collapsible`        | `collapsible`         | Root provider, manages open/close state   | Yes      |
| `CollapsibleTrigger` | `collapsible-trigger` | Button that toggles the collapsible panel | Yes      |
| `CollapsibleContent` | `collapsible-content` | The panel that is shown or hidden         | Yes      |

## Examples

### Disabled

```tsx
"use client";

import { ChevronsUpDown } from "lucide-react";

import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
} from "@/components/ui/collapsible";

export default function CollapsibleDisabled() {
  return (
    <Collapsible disabled className="w-[340px] space-y-2">
      <div className="flex items-center justify-between gap-4">
        <h4 className="text-sm font-semibold">3 items tagged</h4>
        <CollapsibleTrigger className="inline-flex size-9 items-center justify-center rounded-md border border-border bg-transparent hover-only:hover:bg-surface-secondary disabled:pointer-events-none disabled:opacity-50">
          <ChevronsUpDown className="size-4" />
          <span className="sr-only">Toggle</span>
        </CollapsibleTrigger>
      </div>
      <div className="rounded-md border border-border px-4 py-3 text-sm">
        @prototyperco/ui
      </div>
      <CollapsibleContent className="space-y-2">
        <div className="rounded-md border border-border px-4 py-3 text-sm">
          @prototyperco/cli
        </div>
        <div className="rounded-md border border-border px-4 py-3 text-sm">
          @prototyperco/mcp
        </div>
      </CollapsibleContent>
    </Collapsible>
  );
}
```

## Styling

### Data Slots

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

| Slot name             | Element                          |
| --------------------- | -------------------------------- |
| `collapsible`         | Root provider (wrapping element) |
| `collapsible-trigger` | The trigger button               |
| `collapsible-content` | The collapsible panel            |

### Customization Examples

```css
/* Animate the collapsible panel height */
[data-slot="collapsible-content"] {
  overflow: hidden;
  transition: height 250ms var(--ease-out-fluid);
}

[data-slot="collapsible-content"][data-open] {
  height: var(--collapsible-panel-height);
}

[data-slot="collapsible-content"][data-closed] {
  height: 0;
}
```

```tsx
{
  /* Override styling via className */
}
<CollapsibleContent className="mt-4 space-y-2">{/* ... */}</CollapsibleContent>;
```

## API Reference

### Collapsible

Root component that manages the open/close state of the collapsible section.

| 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 |
| `disabled` | `boolean` | `false` | Whether the collapsible should ignore user interaction |
| `className` | `string` | - | Additional CSS classes |

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

### CollapsibleTrigger

Button that toggles the collapsible panel open and closed.

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

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

### CollapsibleContent

The panel that is shown or hidden when the collapsible is toggled.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `hiddenUntilFound` | `boolean` | `false` | Uses hidden="until-found" to allow browser search to reveal the content |
| `keepMounted` | `boolean` | `false` | Whether the panel stays in the DOM when closed |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Panel content |

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

## Accessibility

### Keyboard Interactions

| Key     | Action                                 |
| ------- | -------------------------------------- |
| `Space` | Toggles the collapsible panel          |
| `Enter` | Toggles the collapsible panel          |
| `Tab`   | Moves focus to / away from the trigger |

### ARIA Attributes

- `CollapsibleTrigger` renders as a `<button>` element with `aria-expanded` reflecting the open state.
- `aria-controls` on the trigger is automatically linked to the `CollapsibleContent` panel.
- `CollapsibleContent` has `role="region"` for screen reader discoverability.
- When `disabled` is set, the trigger receives the `disabled` attribute and interaction is prevented.

## Full Component Source

```tsx
"use client";

export {
  Collapsible,
  CollapsibleTrigger,
  CollapsibleContent,
} from "@prototyperco/ui/components/collapsible";
```
</component>

<component name="color-picker" url="https://prototyper-ui.com/docs/components/color-picker">
# Color Picker
> An OKLCH-native color picker with area, sliders, swatches, and eye dropper
URL: https://prototyper-ui.com/docs/components/color-picker
```tsx
import {
  ColorPicker,
  ColorPickerArea,
  ColorPickerContent,
  ColorPickerEyeDropper,
  ColorPickerInput,
  ColorPickerSlider,
  ColorPickerTrigger,
} from "@/components/ui/color-picker";

export default function ColorPickerDemo() {
  return (
    <ColorPicker defaultValue="#6366f1">
      <ColorPickerTrigger />
      <ColorPickerContent>
        <ColorPickerArea />
        <ColorPickerSlider channel="hue" />
        <div className="flex gap-2">
          <ColorPickerEyeDropper />
          <ColorPickerInput />
        </div>
      </ColorPickerContent>
    </ColorPicker>
  );
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/color-picker.tsx`
- `lib/color-utils.ts`

## Usage

```tsx
import {
  ColorPicker,
  ColorPickerArea,
  ColorPickerContent,
  ColorPickerInput,
  ColorPickerSlider,
  ColorPickerTrigger,
} from "@/components/ui/color-picker";

<ColorPicker defaultValue="#6366f1">
  <ColorPickerTrigger />
  <ColorPickerContent>
    <ColorPickerArea />
    <ColorPickerSlider channel="hue" />
    <ColorPickerInput />
  </ColorPickerContent>
</ColorPicker>;
```

## Anatomy

```tsx
<ColorPicker>
  <ColorPickerTrigger />
  <ColorPickerContent>
    <ColorPickerArea>
      <ColorPickerAreaThumb />
    </ColorPickerArea>
    <ColorPickerSlider channel="hue">
      <ColorPickerSliderThumb />
    </ColorPickerSlider>
    <ColorPickerSlider channel="alpha">
      <ColorPickerSliderThumb />
    </ColorPickerSlider>
    <ColorPickerEyeDropper />
    <ColorPickerInput />
    <ColorPickerSwatches>
      <ColorPickerSwatch />
    </ColorPickerSwatches>
  </ColorPickerContent>
</ColorPicker>
```

| Sub-component            | `data-slot`                 | Purpose                                    | Required |
| ------------------------ | --------------------------- | ------------------------------------------ | -------- |
| `ColorPicker`            | `color-picker`              | Root context provider, manages color state | Yes      |
| `ColorPickerTrigger`     | `color-picker-trigger`      | Button that opens the popover              | No       |
| `ColorPickerContent`     | `color-picker-content`      | Popover panel containing controls          | No       |
| `ColorPickerArea`        | `color-picker-area`         | 2D lightness × chroma gradient             | Yes      |
| `ColorPickerAreaThumb`   | `color-picker-area-thumb`   | Draggable dot in the area                  | No       |
| `ColorPickerSlider`      | `color-picker-slider`       | 1D channel slider (hue or alpha)           | Yes      |
| `ColorPickerSliderThumb` | `color-picker-slider-thumb` | Slider thumb                               | No       |
| `ColorPickerInput`       | `color-picker-input`        | Text input for hex/color values            | No       |
| `ColorPickerEyeDropper`  | `color-picker-eye-dropper`  | EyeDropper API button (progressive)        | No       |
| `ColorPickerSwatches`    | `color-picker-swatches`     | Grid container for preset colors           | No       |
| `ColorPickerSwatch`      | `color-picker-swatch`       | Clickable preset color button              | No       |

## Examples

### With Swatches

```tsx
import {
  ColorPicker,
  ColorPickerArea,
  ColorPickerContent,
  ColorPickerEyeDropper,
  ColorPickerInput,
  ColorPickerSlider,
  ColorPickerSwatch,
  ColorPickerSwatches,
  ColorPickerTrigger,
} from "@/components/ui/color-picker";

const presets = [
  "#ef4444",
  "#f97316",
  "#eab308",
  "#22c55e",
  "#06b6d4",
  "#3b82f6",
  "#6366f1",
  "#a855f7",
  "#ec4899",
  "#f43f5e",
  "#64748b",
  "#000000",
];

export default function ColorPickerSwatchesDemo() {
  return (
    <ColorPicker defaultValue="#3b82f6">
      <ColorPickerTrigger />
      <ColorPickerContent>
        <ColorPickerArea />
        <ColorPickerSlider channel="hue" />
        <div className="flex gap-2">
          <ColorPickerEyeDropper />
          <ColorPickerInput />
        </div>
        <ColorPickerSwatches>
          {presets.map((color) => (
            <ColorPickerSwatch key={color} value={color} />
          ))}
        </ColorPickerSwatches>
      </ColorPickerContent>
    </ColorPicker>
  );
}
```

### Alpha Channel

```tsx
import {
  ColorPicker,
  ColorPickerArea,
  ColorPickerContent,
  ColorPickerInput,
  ColorPickerSlider,
  ColorPickerTrigger,
} from "@/components/ui/color-picker";

export default function ColorPickerAlphaDemo() {
  return (
    <ColorPicker defaultValue="#6366f1" enableAlpha>
      <ColorPickerTrigger />
      <ColorPickerContent>
        <ColorPickerArea />
        <ColorPickerSlider channel="hue" />
        <ColorPickerSlider channel="alpha" />
        <ColorPickerInput />
      </ColorPickerContent>
    </ColorPicker>
  );
}
```

### Inline

```tsx
"use client";

import { useState } from "react";

import {
  ColorPicker,
  ColorPickerArea,
  ColorPickerEyeDropper,
  ColorPickerInput,
  ColorPickerSlider,
} from "@/components/ui/color-picker";

export default function ColorPickerInlineDemo() {
  const [color, setColor] = useState("#22c55e");

  return (
    <div className="flex items-start gap-6">
      <ColorPicker value={color} onValueChange={setColor}>
        <div className="flex w-64 flex-col gap-3 rounded-lg border border-border bg-surface p-3">
          <ColorPickerArea />
          <ColorPickerSlider channel="hue" />
          <div className="flex gap-2">
            <ColorPickerEyeDropper />
            <ColorPickerInput />
          </div>
        </div>
      </ColorPicker>
      <div
        className="size-16 rounded-lg border border-border shadow-sm"
        style={{ backgroundColor: color }}
      />
    </div>
  );
}
```

### Form Integration

```tsx
"use client";

import { useState } from "react";

import { Button } from "@/components/ui/button";
import {
  ColorPicker,
  ColorPickerArea,
  ColorPickerContent,
  ColorPickerInput,
  ColorPickerSlider,
  ColorPickerTrigger,
} from "@/components/ui/color-picker";
import { FieldLabel } from "@/components/ui/field";

export default function ColorPickerFormDemo() {
  const [submitted, setSubmitted] = useState<string | null>(null);

  return (
    <form
      className="flex flex-col gap-4"
      onSubmit={(e) => {
        e.preventDefault();
        const data = new FormData(e.currentTarget);
        setSubmitted(data.get("accent-color") as string);
      }}
    >
      <div className="flex flex-col gap-1.5">
        <FieldLabel>Accent Color</FieldLabel>
        <ColorPicker defaultValue="#6366f1" name="accent-color">
          <ColorPickerTrigger />
          <ColorPickerContent>
            <ColorPickerArea />
            <ColorPickerSlider channel="hue" />
            <ColorPickerInput />
          </ColorPickerContent>
        </ColorPicker>
      </div>
      <Button type="submit" className="w-fit">
        Submit
      </Button>
      {submitted && (
        <p className="text-sm text-muted-foreground">
          Submitted:{" "}
          <code className="font-mono text-foreground">{submitted}</code>
        </p>
      )}
    </form>
  );
}
```

### Disabled

```tsx
import {
  ColorPicker,
  ColorPickerArea,
  ColorPickerContent,
  ColorPickerInput,
  ColorPickerSlider,
  ColorPickerTrigger,
} from "@/components/ui/color-picker";

export default function ColorPickerDisabledDemo() {
  return (
    <ColorPicker defaultValue="#6366f1" disabled>
      <ColorPickerTrigger />
      <ColorPickerContent>
        <ColorPickerArea />
        <ColorPickerSlider channel="hue" />
        <ColorPickerInput />
      </ColorPickerContent>
    </ColorPicker>
  );
}
```

## Styling

### Data Slots

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

| Slot name                   | Element                            |
| --------------------------- | ---------------------------------- |
| `color-picker`              | Root wrapper                       |
| `color-picker-trigger`      | Trigger button with swatch preview |
| `color-picker-content`      | Popover panel                      |
| `color-picker-area`         | 2D color gradient canvas           |
| `color-picker-area-thumb`   | Draggable dot on the area          |
| `color-picker-slider`       | Hue or alpha slider track          |
| `color-picker-slider-thumb` | Slider thumb circle                |
| `color-picker-input`        | Hex text input                     |
| `color-picker-eye-dropper`  | EyeDropper button                  |
| `color-picker-swatches`     | Swatches grid container            |
| `color-picker-swatch`       | Individual swatch button           |

### Customization Examples

```css
/* Make the color area taller */
[data-slot="color-picker-area"] {
  @apply aspect-[4/3];
}

/* Larger swatches */
[data-slot="color-picker-swatch"] {
  @apply size-8 rounded-full;
}
```

```tsx
{
  /* Wider popover panel */
}
<ColorPickerContent className="w-80">{/* ... */}</ColorPickerContent>;
```

## API Reference

### ColorPicker

Root component that manages color state and provides context.

| Prop            | Type                                 | Default     | Description                           |
| --------------- | ------------------------------------ | ----------- | ------------------------------------- |
| `value`         | `string`                             | -           | Controlled CSS color string           |
| `defaultValue`  | `string`                             | `"#6366f1"` | Uncontrolled initial color            |
| `onValueChange` | `(value: string) => void`            | -           | Called on every change (live)         |
| `onValueCommit` | `(value: string) => void`            | -           | Called on pointer up or Enter         |
| `outputFormat`  | `"hex" \| "oklch" \| "rgb" \| "hsl"` | `"hex"`     | Format for emitted color strings      |
| `name`          | `string`                             | -           | Hidden input name for form submission |
| `disabled`      | `boolean`                            | `false`     | Disable all interactions              |
| `enableAlpha`   | `boolean`                            | `false`     | Show alpha channel controls           |
| `open`          | `boolean`                            | -           | Controlled popover open state         |
| `onOpenChange`  | `(open: boolean) => void`            | -           | Callback when popover opens/closes    |
| `className`     | `string`                             | -           | Additional CSS classes                |
| `children`      | `React.ReactNode`                    | -           | Color picker content                  |

### ColorPickerTrigger

Button that shows a swatch preview and opens the popover.

| Prop        | Type                             | Default | Description                                    |
| ----------- | -------------------------------- | ------- | ---------------------------------------------- |
| `className` | `string`                         | -       | Additional CSS classes                         |
| `children`  | `React.ReactNode`                | -       | Custom trigger content (defaults to hex value) |
| `...props`  | `PopoverPrimitive.Trigger.Props` | -       | All Base UI Popover.Trigger props              |

### ColorPickerContent

Popover panel wrapping the color controls.

| Prop         | Type                           | Default   | Description                     |
| ------------ | ------------------------------ | --------- | ------------------------------- |
| `sideOffset` | `number`                       | `8`       | Distance from trigger           |
| `align`      | `"start" \| "center" \| "end"` | `"start"` | Alignment relative to trigger   |
| `className`  | `string`                       | -         | Additional CSS classes          |
| `...props`   | `PopoverPrimitive.Popup.Props` | -         | All Base UI Popover.Popup props |

### ColorPickerArea

2D gradient area for selecting lightness (Y) and chroma (X).

| Prop        | Type              | Default | Description                                     |
| ----------- | ----------------- | ------- | ----------------------------------------------- |
| `className` | `string`          | -       | Additional CSS classes                          |
| `children`  | `React.ReactNode` | -       | Custom thumb (defaults to ColorPickerAreaThumb) |

### ColorPickerAreaThumb

Draggable dot positioned within the color area.

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

### ColorPickerSlider

1D slider for hue or alpha channel.

| Prop        | Type               | Default | Description                                       |
| ----------- | ------------------ | ------- | ------------------------------------------------- |
| `channel`   | `"hue" \| "alpha"` | -       | Which channel to control                          |
| `className` | `string`           | -       | Additional CSS classes                            |
| `children`  | `React.ReactNode`  | -       | Custom thumb (defaults to ColorPickerSliderThumb) |

### ColorPickerSliderThumb

Slider thumb circle.

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

### ColorPickerInput

Text input for typing color values directly.

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

### ColorPickerEyeDropper

Button that activates the browser EyeDropper API. Only renders when the API is available.

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

### ColorPickerSwatches

Grid container for preset color buttons.

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

### ColorPickerSwatch

Clickable preset color button.

| Prop        | Type     | Default | Description                      |
| ----------- | -------- | ------- | -------------------------------- |
| `value`     | `string` | -       | CSS color string for this preset |
| `className` | `string` | -       | Additional CSS classes           |

## Accessibility

### Keyboard Interactions

| Key                  | Action                                                |
| -------------------- | ----------------------------------------------------- |
| `Arrow keys`         | Move thumb in the color area or adjust slider value   |
| `Shift + Arrow keys` | Fine-step adjustment                                  |
| `Home`               | Set chroma to minimum (area) or slider to minimum     |
| `End`                | Set chroma to maximum (area) or slider to maximum     |
| `PageUp`             | Set lightness to maximum (area only)                  |
| `PageDown`           | Set lightness to minimum (area only)                  |
| `Enter`              | Confirm text input value                              |
| `Tab`                | Move focus between area, sliders, input, and swatches |

### ARIA Attributes

- The color area and sliders use `role="slider"` with `aria-valuemin`, `aria-valuemax`, and `aria-valuenow`.
- `aria-valuetext` on the area provides a human-readable description of the current color position.
- `aria-label` is set on each slider to identify the channel (Hue, Alpha).
- The EyeDropper button is a standard `<button>` element and only renders when the API is supported.

## Full Component Source

```tsx
"use client";

export {
  ColorPicker,
  ColorPickerTrigger,
  ColorPickerContent,
  ColorPickerArea,
  ColorPickerAreaThumb,
  ColorPickerSlider,
  ColorPickerSliderThumb,
  ColorPickerInput,
  ColorPickerEyeDropper,
  ColorPickerSwatches,
  ColorPickerSwatch,
} from "@prototyperco/ui/components/color-picker";
```
</component>

<component name="columns" url="https://prototyper-ui.com/docs/components/columns">
# Columns
> A responsive column grid with configurable count, gap, and collapse breakpoint.
URL: https://prototyper-ui.com/docs/components/columns
```tsx
import { Columns } from "@/components/ui/columns";

export default function ColumnsDemo() {
  return (
    <Columns count={3} gap={4}>
      <div className="rounded-lg bg-muted p-4">
        <h3 className="font-semibold">Column 1</h3>
        <p className="text-sm text-muted-foreground">First column content</p>
      </div>
      <div className="rounded-lg bg-muted p-4">
        <h3 className="font-semibold">Column 2</h3>
        <p className="text-sm text-muted-foreground">Second column content</p>
      </div>
      <div className="rounded-lg bg-muted p-4">
        <h3 className="font-semibold">Column 3</h3>
        <p className="text-sm text-muted-foreground">Third column content</p>
      </div>
    </Columns>
  );
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/columns.tsx`

## Usage

```tsx
import { Columns, Column } from "@/components/ui/columns";
```

```tsx
<Columns count={3} gap={4}>
  <div>Column 1</div>
  <div>Column 2</div>
  <div>Column 3</div>
</Columns>
```

Columns creates a responsive CSS grid that starts as a single column and expands to `count` columns above the `collapse` breakpoint. Use `Column` for items that need to span multiple grid tracks.

## Anatomy

```tsx
<Columns count={3} gap={4} collapse="md">
  <Column span={2}>Wide column</Column>
  <Column>Normal column</Column>
</Columns>
```

| Sub-component | `data-slot` | Purpose                                | Required |
| ------------- | ----------- | -------------------------------------- | -------- |
| `Columns`     | `columns`   | Grid container with responsive columns | Yes      |
| `Column`      | `column`    | Grid item with optional span           | No       |

## Examples

### Two Columns

```tsx
import { Columns } from "@/components/ui/columns";

export default function ColumnsTwo() {
  return (
    <Columns count={2} gap={6}>
      <div className="rounded-lg bg-muted p-4">
        <h3 className="font-semibold">Left Column</h3>
        <p className="text-sm text-muted-foreground">
          A simple two-column layout that stacks on smaller screens.
        </p>
      </div>
      <div className="rounded-lg bg-muted p-4">
        <h3 className="font-semibold">Right Column</h3>
        <p className="text-sm text-muted-foreground">
          Content in the second column sits side by side above the breakpoint.
        </p>
      </div>
    </Columns>
  );
}
```

### Asymmetric Layout

Use `Column` with `span` to create uneven splits like a sidebar layout.

```tsx
import { Columns, Column } from "@/components/ui/columns";

export default function ColumnsAsymmetric() {
  return (
    <Columns count={3} gap={6}>
      <Column span={2}>
        <div className="rounded-lg bg-muted p-4">
          <h3 className="font-semibold">Main Content</h3>
          <p className="text-sm text-muted-foreground">
            This column spans 2 of 3 grid columns, creating a 2:1 split that
            works well for sidebar layouts.
          </p>
        </div>
      </Column>
      <Column>
        <div className="rounded-lg bg-surface-secondary p-4">
          <h3 className="font-semibold">Sidebar</h3>
          <p className="text-sm text-muted-foreground">
            Narrow sidebar column.
          </p>
        </div>
      </Column>
    </Columns>
  );
}
```

### Responsive Collapse

Columns collapse to a single column below the `collapse` breakpoint. Compare `md` (default) and `lg` collapse points.

```tsx
import { Columns } from "@/components/ui/columns";

export default function ColumnsResponsive() {
  return (
    <div className="space-y-6">
      <div>
        <p className="mb-2 text-sm font-medium text-muted-foreground">
          Collapses at md (default)
        </p>
        <Columns count={4} gap={4} collapse="md">
          {Array.from({ length: 4 }, (_, i) => (
            <div key={i} className="rounded-lg bg-muted p-4 text-center">
              <span className="text-sm font-semibold">{i + 1}</span>
            </div>
          ))}
        </Columns>
      </div>
      <div>
        <p className="mb-2 text-sm font-medium text-muted-foreground">
          Collapses at lg
        </p>
        <Columns count={4} gap={4} collapse="lg">
          {Array.from({ length: 4 }, (_, i) => (
            <div key={i} className="rounded-lg bg-muted p-4 text-center">
              <span className="text-sm font-semibold">{i + 1}</span>
            </div>
          ))}
        </Columns>
      </div>
    </div>
  );
}
```

## Styling

### Data Slots

Use `data-slot` attributes to target Columns parts in CSS:

| Slot name | Element               |
| --------- | --------------------- |
| `columns` | The grid `<div>` root |
| `column`  | A grid item `<div>`   |

### Customization Examples

```css
/* Add a border between columns */
[data-slot="column"] + [data-slot="column"] {
  @apply border-l border-border pl-4;
}
```

```tsx
<Columns className="rounded-lg bg-muted p-4" count={2} gap={6}>
  Custom styled grid
</Columns>
```

## API Reference

### Columns

A responsive grid container.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `count` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `3` | Number of columns above the collapse breakpoint. |
| `gap` | `number` | `4` | Gap between columns. Maps to Tailwind gap utilities (0, 1, 2, 3, 4, 5, 6, 8, 10, 12). |
| `collapse` | `"sm" \| "md" \| "lg" \| "never"` | `"md"` | Breakpoint below which columns collapse to a single column. Use "never" to always show the grid. |
| `className` | `string` | - | Additional CSS classes. |
| `children` | `React.ReactNode` | - | Column children. |

Extends `React.ComponentProps<"div">`. All standard div props are forwarded via `...props`.

### Column

A grid item with optional span control.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `span` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` | Number of grid columns this item spans. |
| `collapse` | `"sm" \| "md" \| "lg" \| "never"` | `"md"` | Breakpoint at which the span takes effect. Should match the parent Columns collapse prop. |
| `className` | `string` | - | Additional CSS classes. |
| `children` | `React.ReactNode` | - | Column content. |

Extends `React.ComponentProps<"div">`. All standard div props are forwarded via `...props`.

## Accessibility

### Keyboard Interactions

Columns is a non-interactive layout container and does not have keyboard interactions.

### ARIA Attributes

- Renders as a plain `<div>` with CSS Grid, no implicit ARIA role.
- No additional ARIA attributes are needed for a grid layout container.

## Full Component Source

```tsx
"use client";

export { Columns, Column } from "@prototyperco/ui/components/columns";
```
</component>

<component name="combobox" url="https://prototyper-ui.com/docs/components/combobox">
# Combobox
> 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.

## Full Component Source

```tsx
"use client";

export {
  Combobox,
  ComboboxCollection,
  ComboboxInput,
  ComboboxChipsInput,
  ComboboxContent,
  ComboboxList,
  ComboboxItem,
  ComboboxEmpty,
  ComboboxGroup,
  ComboboxGroupLabel,
  ComboboxLabel,
  ComboboxSeparator,
  ComboboxTrigger,
  ComboboxClear,
  ComboboxValue,
  ComboboxIcon,
  ComboboxChips,
  ComboboxChip,
  ComboboxChipRemove,
  ComboboxStatus,
  ComboboxArrow,
  ComboboxBackdrop,
  useComboboxAnchor,
  useComboboxFilter,
} from "@prototyperco/ui/components/combobox";
```
</component>

<component name="command-palette" url="https://prototyper-ui.com/docs/components/command-palette">
# Command Palette
> A command palette with search, groups, and keyboard navigation built on Base UI
URL: https://prototyper-ui.com/docs/components/command-palette
Base UI reference: https://base-ui.com/react/components/dialog
```tsx
"use client";

import * as React from "react";
import {
  CommandPalette,
  CommandPaletteContent,
  CommandInput,
  CommandGroup,
  CommandItem,
  CommandEmpty,
  CommandSeparator,
  CommandList,
} from "@/components/ui/command-palette";
import { Button } from "@/components/ui/button";

export default function CommandPaletteDemo() {
  const [open, setOpen] = React.useState(false);

  return (
    <>
      <Button variant="outline" onClick={() => setOpen(true)}>
        Open Command Palette
      </Button>
      <CommandPalette open={open} onOpenChange={setOpen}>
        <CommandPaletteContent>
          <CommandInput placeholder="Type a command or search..." />
          <CommandList>
            <CommandEmpty>No results found.</CommandEmpty>
            <CommandGroup heading="Suggestions">
              <CommandItem value="Calendar" onSelect={() => setOpen(false)}>
                Calendar
              </CommandItem>
              <CommandItem value="Search" onSelect={() => setOpen(false)}>
                Search
              </CommandItem>
              <CommandItem value="Settings" onSelect={() => setOpen(false)}>
                Settings
              </CommandItem>
            </CommandGroup>
            <CommandSeparator />
            <CommandGroup heading="Actions">
              <CommandItem
                value="New File"
                shortcut="Ctrl+N"
                onSelect={() => setOpen(false)}
              >
                New File
              </CommandItem>
              <CommandItem
                value="New Window"
                shortcut="Ctrl+Shift+N"
                onSelect={() => setOpen(false)}
              >
                New Window
              </CommandItem>
              <CommandItem value="Quit" shortcut="Ctrl+Q" disabled>
                Quit
              </CommandItem>
            </CommandGroup>
          </CommandList>
        </CommandPaletteContent>
      </CommandPalette>
    </>
  );
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/command-palette.tsx`

## Usage

```tsx
import {
  CommandPalette,
  CommandPaletteContent,
  CommandInput,
  CommandGroup,
  CommandItem,
  CommandEmpty,
  CommandList,
} from "@/components/ui/command-palette";

<CommandPalette open={open} onOpenChange={setOpen}>
  <CommandPaletteContent>
    <CommandInput />
    <CommandList>
      <CommandEmpty>No results found.</CommandEmpty>
      <CommandGroup heading="Actions">
        <CommandItem value="Search" onSelect={() => {}}>
          Search
        </CommandItem>
      </CommandGroup>
    </CommandList>
  </CommandPaletteContent>
</CommandPalette>;
```

## Anatomy

```tsx
<CommandPalette>
  <CommandPaletteContent>
    <CommandInput />
    <CommandList>
      <CommandEmpty />
      <CommandGroup>
        <CommandItem />
      </CommandGroup>
      <CommandSeparator />
    </CommandList>
  </CommandPaletteContent>
</CommandPalette>
```

| Sub-component           | `data-slot`               | Purpose                                            | Required |
| ----------------------- | ------------------------- | -------------------------------------------------- | -------- |
| `CommandPalette`        | `command-palette`         | Root provider, manages open/close state and search | Yes      |
| `CommandPaletteContent` | `command-palette-content` | The popup panel with overlay backdrop              | Yes      |
| `CommandInput`          | `command-input`           | Text input for filtering items                     | Yes      |
| `CommandList`           | `command-list`            | Scrollable container for groups and items          | Yes      |
| `CommandGroup`          | `command-group`           | Groups related items with an optional heading      | No       |
| `CommandItem`           | `command-item`            | Individual selectable command item                 | Yes      |
| `CommandEmpty`          | `command-empty`           | Shown when search yields no results                | No       |
| `CommandSeparator`      | `command-separator`       | Visual divider between groups                      | No       |

## Styling

### Data Slots

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

| Slot name                 | Element                                |
| ------------------------- | -------------------------------------- |
| `command-palette`         | Root provider (no DOM element)         |
| `command-palette-portal`  | Portal wrapper                         |
| `command-palette-overlay` | Backdrop overlay                       |
| `command-palette-content` | The popup panel                        |
| `command-input-wrapper`   | Wrapper around the search icon + input |
| `command-input`           | The search input element               |
| `command-list`            | Scrollable items container             |
| `command-group`           | Group wrapper                          |
| `command-group-heading`   | Group heading text                     |
| `command-item`            | Individual item row                    |
| `command-shortcut`        | Keyboard shortcut badge                |
| `command-empty`           | Empty state message                    |
| `command-separator`       | Divider line                           |

### Customization Examples

```css
/* Widen the command palette */
[data-slot="command-palette-content"] {
  @apply max-w-2xl;
}

/* Custom item highlight color */
[data-slot="command-item"][data-highlighted] {
  @apply bg-primary/10;
}
```

```tsx
{
  /* Override styles via className */
}
<CommandPaletteContent className="max-w-2xl">
  {/* ... */}
</CommandPaletteContent>;
```

## API Reference

### CommandPalette

Root component that manages dialog state, search state, and item registration.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | - | Controlled open state |
| `onOpenChange` | `(open: boolean) => void` | - | Callback when open state changes |
| `filter` | `(value: string, search: string) => boolean` | - | Custom filter function (defaults to case-insensitive includes) |
| `children` | `React.ReactNode` | - | Command palette content |

### CommandPaletteContent

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

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

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

### CommandInput

Search input that filters items and handles keyboard navigation.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `placeholder` | `string` | `"Type a command or search..."` | Placeholder text for the input |
| `className` | `string` | - | Additional CSS classes |

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

### CommandList

Scrollable container for command groups and items.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Groups, items, separators |

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

### CommandGroup

Groups related items under an optional heading.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `heading` | `string` | - | Group heading label |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Command items |

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

### CommandItem

An individual selectable command.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | - | Value used for filtering against the search query |
| `onSelect` | `() => void` | - | Callback when the item is selected (click or Enter) |
| `disabled` | `boolean` | `false` | Whether the item is disabled |
| `shortcut` | `string` | - | Keyboard shortcut to display on the right side |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Item content |

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

### CommandEmpty

Placeholder content shown when the search query matches no items.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | `"No results found."` | Custom empty state content |

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

### CommandSeparator

A visual divider between groups.

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

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

## Accessibility

### Keyboard Interactions

| Key         | Action                                       |
| ----------- | -------------------------------------------- |
| `ArrowDown` | Moves highlight to the next enabled item     |
| `ArrowUp`   | Moves highlight to the previous enabled item |
| `Enter`     | Selects the currently highlighted item       |
| `Escape`    | Closes the command palette                   |
| `Tab`       | Moves focus to the next focusable element    |

### ARIA Attributes

- Each `CommandItem` renders with `role="option"` and `aria-selected` reflecting the highlight state.
- `aria-disabled` is set on disabled items.
- The dialog is modal -- focus is trapped inside while open.
- The search input receives auto-focus when the palette opens.

## Full Component Source

```tsx
"use client";

export {
  CommandPalette,
  CommandPaletteContent,
  CommandInput,
  CommandGroup,
  CommandItem,
  CommandEmpty,
  CommandSeparator,
  CommandList,
} from "@prototyperco/ui/components/command-palette";
```
</component>

<component name="container" url="https://prototyper-ui.com/docs/components/container">
# Container
> A content constraint wrapper with max-width and padding options.
URL: https://prototyper-ui.com/docs/components/container
```tsx
import { Container } from "@/components/ui/container";

export default function ContainerDemo() {
  return (
    <div className="space-y-4">
      <Container maxWidth="5xl" className="rounded-lg bg-muted p-4">
        <p className="text-sm text-muted-foreground">
          Default container (max-w-5xl)
        </p>
      </Container>
      <Container maxWidth="4xl" className="rounded-lg bg-muted p-4">
        <p className="text-sm text-muted-foreground">
          Narrower container (max-w-4xl)
        </p>
      </Container>
      <Container maxWidth="2xl" className="rounded-lg bg-muted p-4">
        <p className="text-sm text-muted-foreground">
          Narrow container (max-w-2xl)
        </p>
      </Container>
    </div>
  );
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/container.tsx`

## Usage

```tsx
import { Container } from "@/components/ui/container";
```

```tsx
<Container maxWidth="4xl" padding="md">
  <p>Content is constrained and centered.</p>
</Container>
```

Container is a simple `<div>` that constrains its children to a max-width and adds horizontal padding. Use it inside a Section or on its own when you need to center page content.

## Examples

### Narrow Content

```tsx
import { Container } from "@/components/ui/container";

export default function ContainerNarrow() {
  return (
    <Container maxWidth="lg" padding="md">
      <article className="space-y-4">
        <h2 className="text-2xl font-bold">Article Title</h2>
        <p className="text-muted-foreground">
          A narrow, centered container is ideal for article-style content. The
          constrained width keeps line lengths comfortable for reading while the
          padding ensures breathing room on smaller screens.
        </p>
        <p className="text-muted-foreground">
          Use <code className="text-sm font-mono">maxWidth=&quot;lg&quot;</code>{" "}
          or <code className="text-sm font-mono">maxWidth=&quot;2xl&quot;</code>{" "}
          depending on your content density.
        </p>
      </article>
    </Container>
  );
}
```

## Styling

### Data Slots

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

| Slot name   | Element          |
| ----------- | ---------------- |
| `container` | The `<div>` root |

### Customization Examples

```css
/* Add vertical padding to all containers */
[data-slot="container"] {
  @apply py-8;
}
```

```tsx
<Container className="py-12" maxWidth="2xl">
  Custom styled container
</Container>
```

## API Reference

### Container

A centered, width-constrained content wrapper.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `maxWidth` | `"sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "4xl" \| "5xl" \| "full"` | `"5xl"` | Maximum width constraint. |
| `padding` | `"none" \| "sm" \| "md" \| "lg"` | `"md"` | Horizontal padding. |
| `centered` | `boolean` | `true` | Whether to center the container with mx-auto. |
| `className` | `string` | - | Additional CSS classes. |
| `children` | `React.ReactNode` | - | Container content. |

Extends `React.ComponentProps<"div">`. All standard div props are forwarded via `...props`.

## Accessibility

### Keyboard Interactions

Container is a non-interactive presentational wrapper and does not have keyboard interactions.

### ARIA Attributes

- Renders as a plain `<div>` with no implicit ARIA role.
- No additional ARIA attributes are needed for a layout container.

## Full Component Source

```tsx
"use client";

export { Container } from "@prototyperco/ui/components/container";
```
</component>

<component name="context-menu" url="https://prototyper-ui.com/docs/components/context-menu">
# Context Menu
> right-click menu with submenus and checkbox/radio items
URL: https://prototyper-ui.com/docs/components/context-menu
Base UI reference: https://base-ui.com/react/components/menu
```tsx
import {
  ContextMenu,
  ContextMenuContent,
  ContextMenuItem,
  ContextMenuSeparator,
  ContextMenuShortcut,
  ContextMenuSub,
  ContextMenuSubContent,
  ContextMenuSubTrigger,
  ContextMenuTrigger,
} from "@/components/ui/context-menu";

export default function ContextMenuDemo() {
  return (
    <ContextMenu>
      <ContextMenuTrigger className="flex h-36 w-64 items-center justify-center rounded-md border border-dashed text-sm text-muted-foreground">
        Right click here
      </ContextMenuTrigger>
      <ContextMenuContent className="w-48">
        <ContextMenuItem>
          Back
          <ContextMenuShortcut>Ctrl+[</ContextMenuShortcut>
        </ContextMenuItem>
        <ContextMenuItem disabled>
          Forward
          <ContextMenuShortcut>Ctrl+]</ContextMenuShortcut>
        </ContextMenuItem>
        <ContextMenuItem>
          Reload
          <ContextMenuShortcut>Ctrl+R</ContextMenuShortcut>
        </ContextMenuItem>
        <ContextMenuSeparator />
        <ContextMenuSub>
          <ContextMenuSubTrigger>More Tools</ContextMenuSubTrigger>
          <ContextMenuSubContent>
            <ContextMenuItem>Save Page As...</ContextMenuItem>
            <ContextMenuItem>Create Shortcut...</ContextMenuItem>
            <ContextMenuItem>Name Window...</ContextMenuItem>
            <ContextMenuSeparator />
            <ContextMenuItem>Developer Tools</ContextMenuItem>
          </ContextMenuSubContent>
        </ContextMenuSub>
        <ContextMenuSeparator />
        <ContextMenuItem>
          View Page Source
          <ContextMenuShortcut>Ctrl+U</ContextMenuShortcut>
        </ContextMenuItem>
        <ContextMenuItem>Inspect</ContextMenuItem>
      </ContextMenuContent>
    </ContextMenu>
  );
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/context-menu.tsx`

## Usage

```tsx
import {
  ContextMenu,
  ContextMenuTrigger,
  ContextMenuContent,
  ContextMenuItem,
} from "@/components/ui/context-menu";

<ContextMenu>
  <ContextMenuTrigger>Right click here</ContextMenuTrigger>
  <ContextMenuContent>
    <ContextMenuItem>Item 1</ContextMenuItem>
    <ContextMenuItem>Item 2</ContextMenuItem>
  </ContextMenuContent>
</ContextMenu>;
```

## Anatomy

```tsx
<ContextMenu>
  <ContextMenuTrigger />
  <ContextMenuContent>
    <ContextMenuLabel />
    <ContextMenuSeparator />
    <ContextMenuGroup>
      <ContextMenuItem />
    </ContextMenuGroup>
    <ContextMenuCheckboxItem />
    <ContextMenuRadioGroup>
      <ContextMenuRadioItem />
    </ContextMenuRadioGroup>
    <ContextMenuSub>
      <ContextMenuSubTrigger />
      <ContextMenuSubContent>
        <ContextMenuItem />
      </ContextMenuSubContent>
    </ContextMenuSub>
  </ContextMenuContent>
</ContextMenu>
```

| Sub-component             | `data-slot`                  | Purpose                                    | Required |
| ------------------------- | ---------------------------- | ------------------------------------------ | -------- |
| `ContextMenu`             | `context-menu`               | Root provider, manages open/close state    | Yes      |
| `ContextMenuTrigger`      | `context-menu-trigger`       | Element that opens the menu on right click | Yes      |
| `ContextMenuPortal`       | `context-menu-portal`        | Renders children into a portal             | No       |
| `ContextMenuContent`      | `context-menu-content`       | The popup panel containing menu items      | Yes      |
| `ContextMenuGroup`        | `context-menu-group`         | Groups related menu items                  | No       |
| `ContextMenuLabel`        | `context-menu-label`         | Non-interactive label for a group          | No       |
| `ContextMenuItem`         | `context-menu-item`          | Individual actionable menu item            | Yes      |
| `ContextMenuCheckboxItem` | `context-menu-checkbox-item` | Toggleable checkbox menu item              | No       |
| `ContextMenuRadioGroup`   | `context-menu-radio-group`   | Groups radio menu items                    | No       |
| `ContextMenuRadioItem`    | `context-menu-radio-item`    | Radio-selectable menu item                 | No       |
| `ContextMenuSeparator`    | `context-menu-separator`     | Visual separator between items             | No       |
| `ContextMenuShortcut`     | `context-menu-shortcut`      | Keyboard shortcut hint text                | No       |
| `ContextMenuSub`          | `context-menu-sub`           | Root for a submenu                         | No       |
| `ContextMenuSubTrigger`   | `context-menu-sub-trigger`   | Item that opens a submenu                  | No       |
| `ContextMenuSubContent`   | `context-menu-sub-content`   | Submenu popup panel                        | No       |

## Examples

### Basic

```tsx
import {
  ContextMenu,
  ContextMenuContent,
  ContextMenuItem,
  ContextMenuSeparator,
  ContextMenuShortcut,
  ContextMenuSub,
  ContextMenuSubContent,
  ContextMenuSubTrigger,
  ContextMenuTrigger,
} from "@/components/ui/context-menu";

export default function ContextMenuDemo() {
  return (
    <ContextMenu>
      <ContextMenuTrigger className="flex h-36 w-64 items-center justify-center rounded-md border border-dashed text-sm text-muted-foreground">
        Right click here
      </ContextMenuTrigger>
      <ContextMenuContent className="w-48">
        <ContextMenuItem>
          Back
          <ContextMenuShortcut>Ctrl+[</ContextMenuShortcut>
        </ContextMenuItem>
        <ContextMenuItem disabled>
          Forward
          <ContextMenuShortcut>Ctrl+]</ContextMenuShortcut>
        </ContextMenuItem>
        <ContextMenuItem>
          Reload
          <ContextMenuShortcut>Ctrl+R</ContextMenuShortcut>
        </ContextMenuItem>
        <ContextMenuSeparator />
        <ContextMenuSub>
          <ContextMenuSubTrigger>More Tools</ContextMenuSubTrigger>
          <ContextMenuSubContent>
            <ContextMenuItem>Save Page As...</ContextMenuItem>
            <ContextMenuItem>Create Shortcut...</ContextMenuItem>
            <ContextMenuItem>Name Window...</ContextMenuItem>
            <ContextMenuSeparator />
            <ContextMenuItem>Developer Tools</ContextMenuItem>
          </ContextMenuSubContent>
        </ContextMenuSub>
        <ContextMenuSeparator />
        <ContextMenuItem>
          View Page Source
          <ContextMenuShortcut>Ctrl+U</ContextMenuShortcut>
        </ContextMenuItem>
        <ContextMenuItem>Inspect</ContextMenuItem>
      </ContextMenuContent>
    </ContextMenu>
  );
}
```

## Styling

### Data Slots

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

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

### Customization Examples

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

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

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

## API Reference

### ContextMenu

Root component that manages open/close state. Opens on right-click of the trigger.

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

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

### ContextMenuTrigger

Element that opens the context menu when right-clicked.

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

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

### ContextMenuContent

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 cursor position |
| `alignOffset` | `number` | `4` | Offset from the alignment edge |
| `side` | `"top" \| "bottom" \| "left" \| "right"` | `"right"` | Preferred side relative to cursor |
| `sideOffset` | `number` | `0` | Gap between cursor and popup |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Menu content |

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

### ContextMenuGroup

Groups related menu items together.

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

### ContextMenuLabel

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 ContextMenu.GroupLabel props](https://base-ui.com/react/components/menu) are forwarded via `...props`.

### ContextMenuItem

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 ContextMenu.Item props](https://base-ui.com/react/components/menu) are forwarded via `...props`.

### ContextMenuCheckboxItem

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 ContextMenu.CheckboxItem props](https://base-ui.com/react/components/menu) are forwarded via `...props`.

### ContextMenuRadioGroup

Groups radio menu items for single-selection behavior.

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

### ContextMenuRadioItem

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 ContextMenu.RadioItem props](https://base-ui.com/react/components/menu) are forwarded via `...props`.

### ContextMenuSeparator

Visual separator between menu items or groups.

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

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

### ContextMenuShortcut

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`.

### ContextMenuSub

Root provider for a submenu.

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

### ContextMenuSubTrigger

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 ContextMenu.SubmenuTrigger props](https://base-ui.com/react/components/menu) are forwarded via `...props`.

### ContextMenuSubContent

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` | `4` | 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 `ContextMenuContent` 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

- `ContextMenuContent` receives `role="menu"`.
- `ContextMenuItem` receives `role="menuitem"`.
- `ContextMenuCheckboxItem` receives `role="menuitemcheckbox"` with `aria-checked`.
- `ContextMenuRadioItem` receives `role="menuitemradio"` with `aria-checked`.
- `ContextMenuSub` 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 area when the menu closes.

## Full Component Source

```tsx
"use client";

export {
  ContextMenu,
  ContextMenuTrigger,
  ContextMenuContent,
  ContextMenuItem,
  ContextMenuCheckboxItem,
  ContextMenuRadioItem,
  ContextMenuLabel,
  ContextMenuSeparator,
  ContextMenuShortcut,
  ContextMenuGroup,
  ContextMenuPortal,
  ContextMenuSub,
  ContextMenuSubContent,
  ContextMenuSubTrigger,
  ContextMenuRadioGroup,
} from "@prototyperco/ui/components/context-menu";
```
</component>

<component name="dialog" url="https://prototyper-ui.com/docs/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/text-field";

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/text-field";

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.

## Compose

This component is available in [`@prototyperco/compose`](/docs/compose).

### Catalog Definition

```typescript title="dialog.catalog.ts"
import { z } from "zod";
import { defineComponent } from "@prototyperco/compose/catalog";

export default defineComponent({
  description:
    "A modal dialog or side sheet overlay. Open/close is controlled via a state binding path.",
  props: z.object({
    title: z.string().describe("Dialog heading text"),
    description: z
      .string()
      .optional()
      .describe("Optional description below the title"),
    openPath: z
      .string()
      .describe("State path (JSON Pointer) for the open/close boolean"),
    side: z
      .enum(["top", "bottom", "left", "right"])
      .optional()
      .describe(
        "When set, renders as a sheet/drawer anchored to this edge instead of a centered modal",
      ),
  }),
  events: [],
  example: { title: "Confirm action", openPath: "/dialogOpen" },
});
```

### Example Spec

```json
{
  "root": "layout",
  "elements": {
    "layout": {
      "type": "Card",
      "props": { "title": "Dialog Example" },
      "children": ["openBtn", "dialog"]
    },
    "openBtn": {
      "type": "Button",
      "props": { "label": "Open Dialog" },
      "$bindState": { "path": "/dialogOpen", "event": "press", "value": true }
    },
    "dialog": {
      "type": "Dialog",
      "props": {
        "title": "Confirm action",
        "description": "Are you sure you want to proceed?",
        "openPath": "/dialogOpen"
      },
      "children": ["confirmBtn"]
    },
    "confirmBtn": {
      "type": "Button",
      "props": { "label": "Confirm", "variant": "default" }
    }
  }
}
```

Learn more in the [Compose documentation](/docs/compose).

## Full Component Source

```tsx
"use client";

export {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogOverlay,
  DialogPortal,
  DialogTitle,
  DialogTrigger,
} from "@prototyperco/ui/components/dialog";
```

## All Examples

### dialog-popover

```tsx
import { Button } from "@/components/ui/button";
import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";
import {
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from "@/components/ui/popover";

export default function DialogPopover() {
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="outline" />}>
        Open dialog
      </DialogTrigger>
      <DialogContent className="sm:max-w-[425px]">
        <DialogHeader>
          <DialogTitle>Account settings</DialogTitle>
        </DialogHeader>
        <div className="flex flex-col gap-4 py-4">
          <p className="text-sm text-muted-foreground">
            Manage your account settings and preferences.
          </p>
          <Popover>
            <PopoverTrigger
              render={<Button variant="outline" className="self-start" />}
            >
              Need help?
            </PopoverTrigger>
            <PopoverContent className="w-72 p-4">
              <PopoverHeader>
                <PopoverTitle>Help</PopoverTitle>
                <PopoverDescription>
                  For help accessing your account, please contact support.
                </PopoverDescription>
              </PopoverHeader>
            </PopoverContent>
          </Popover>
        </div>
        <DialogFooter>
          <DialogClose render={<Button variant="outline" />}>Close</DialogClose>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
}
```

</component>

<component name="drawer" url="https://prototyper-ui.com/docs/components/drawer">
# Drawer
> slide-in panel anchored to any viewport edge
URL: https://prototyper-ui.com/docs/components/drawer
Base UI reference: https://base-ui.com/react/components/drawer
```tsx
import { Button } from "@/components/ui/button";
import {
  Drawer,
  DrawerClose,
  DrawerContent,
  DrawerDescription,
  DrawerFooter,
  DrawerHeader,
  DrawerTitle,
  DrawerTrigger,
} from "@/components/ui/drawer";

export default function DrawerDemo() {
  return (
    <Drawer>
      <DrawerTrigger render={<Button variant="outline" />}>
        Open Drawer
      </DrawerTrigger>
      <DrawerContent>
        <DrawerHeader>
          <DrawerTitle>Move Goal</DrawerTitle>
          <DrawerDescription>Set your daily activity goal.</DrawerDescription>
        </DrawerHeader>
        <div className="p-4 pb-0">
          <div className="flex items-center justify-center space-x-2">
            <div className="flex-1 text-center">
              <div className="text-foreground text-7xl font-bold tracking-tighter">
                350
              </div>
              <div className="text-muted-foreground text-[0.70rem] uppercase">
                Calories/day
              </div>
            </div>
          </div>
        </div>
        <DrawerFooter>
          <Button>Submit</Button>
          <DrawerClose render={<Button variant="outline" />}>
            Cancel
          </DrawerClose>
        </DrawerFooter>
      </DrawerContent>
    </Drawer>
  );
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/drawer.tsx`

## Usage

```tsx
import {
  Drawer,
  DrawerTrigger,
  DrawerContent,
  DrawerHeader,
  DrawerTitle,
  DrawerDescription,
} from "@/components/ui/drawer";

<Drawer>
  <DrawerTrigger>Open</DrawerTrigger>
  <DrawerContent>
    <DrawerHeader>
      <DrawerTitle>Drawer Title</DrawerTitle>
      <DrawerDescription>Drawer description.</DrawerDescription>
    </DrawerHeader>
  </DrawerContent>
</Drawer>;
```

## Anatomy

```tsx
<Drawer>
  <DrawerTrigger />
  <DrawerContent>
    <DrawerHeader>
      <DrawerTitle />
      <DrawerDescription />
    </DrawerHeader>
    {/* your content */}
    <DrawerFooter>
      <DrawerClose />
    </DrawerFooter>
  </DrawerContent>
</Drawer>
```

| Sub-component       | `data-slot`          | Purpose                                  | Required |
| ------------------- | -------------------- | ---------------------------------------- | -------- |
| `Drawer`            | `drawer`             | Root provider, manages open/close state  | Yes      |
| `DrawerTrigger`     | `drawer-trigger`     | Button that opens the drawer             | Yes      |
| `DrawerPortal`      | `drawer-portal`      | Renders children into a portal           | No       |
| `DrawerOverlay`     | `drawer-overlay`     | Backdrop behind the drawer               | No       |
| `DrawerContent`     | `drawer-content`     | The drawer popup panel                   | Yes      |
| `DrawerHeader`      | `drawer-header`      | Flex container for title and description | No       |
| `DrawerTitle`       | `drawer-title`       | Accessible title for the drawer          | Yes      |
| `DrawerDescription` | `drawer-description` | Accessible description for the drawer    | No       |
| `DrawerFooter`      | `drawer-footer`      | Flex container for action buttons        | No       |
| `DrawerClose`       | `drawer-close`       | Button that closes the drawer            | No       |

## Examples

### Directions

Use the `direction` prop on `DrawerContent` to slide the drawer in from any edge.

```tsx
"use client";

import * as React from "react";
import { Button } from "@/components/ui/button";
import {
  Drawer,
  DrawerClose,
  DrawerContent,
  DrawerDescription,
  DrawerFooter,
  DrawerHeader,
  DrawerTitle,
  DrawerTrigger,
} from "@/components/ui/drawer";

const directions = ["top", "right", "bottom", "left"] as const;

export default function DrawerSides() {
  return (
    <div className="flex flex-wrap items-center gap-2">
      {directions.map((direction) => (
        <Drawer key={direction}>
          <DrawerTrigger render={<Button variant="outline" />}>
            {direction.charAt(0).toUpperCase() + direction.slice(1)}
          </DrawerTrigger>
          <DrawerContent direction={direction}>
            <DrawerHeader direction={direction}>
              <DrawerTitle>Drawer from {direction}</DrawerTitle>
              <DrawerDescription>
                This drawer slides in from the {direction}.
              </DrawerDescription>
            </DrawerHeader>
            <div className="p-4">
              <p className="text-muted-foreground text-sm">
                Drawer content goes here. You can place any content inside.
              </p>
            </div>
            <DrawerFooter>
              <DrawerClose render={<Button variant="outline" />}>
                Close
              </DrawerClose>
            </DrawerFooter>
          </DrawerContent>
        </Drawer>
      ))}
    </div>
  );
}
```

## Styling

### Data Slots

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

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

### Customization Examples

```css
/* Make side drawers wider */
[data-slot="drawer-content"][data-drawer-direction="right"],
[data-slot="drawer-content"][data-drawer-direction="left"] {
  @apply sm:max-w-md;
}

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

```tsx
{
  /* Override direction via prop */
}
<DrawerContent direction="right">{/* ... */}</DrawerContent>;
```

## API Reference

### Drawer

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 drawer is modal |

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

### DrawerTrigger

Button that opens the drawer when clicked.

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

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

### DrawerContent

The popup panel rendered inside a portal with an overlay backdrop. Includes an automatic drag handle when `direction` is `"bottom"`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `direction` | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | The edge of the viewport the drawer slides in from |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Drawer content |

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

### DrawerHeader

Flex column container for title and description.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `direction` | `string` | - | When "bottom" or "top", centers text on mobile |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Header content |

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

### DrawerFooter

Flex column container for action buttons.

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

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

### DrawerTitle

Accessible title for the drawer, rendered as a heading.

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

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

### DrawerDescription

Accessible description rendered below the title.

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

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

### DrawerClose

Button that closes the drawer when clicked.

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

### DrawerOverlay

Backdrop overlay behind the drawer.

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

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

### DrawerPortal

Renders children into a React portal.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `React.ReactNode` | - | Content to render in the portal |

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

## Accessibility

### Keyboard Interactions

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

### ARIA Attributes

- `DrawerContent` receives `role="dialog"`.
- `aria-modal="true"` is set when the drawer is modal.
- `aria-labelledby` is automatically linked to `DrawerTitle`.
- `aria-describedby` is automatically linked to `DrawerDescription`.
- Focus is trapped inside the drawer while it is open.
- Focus returns to the trigger element when the drawer closes.

## Full Component Source

```tsx
"use client";

export {
  Drawer,
  DrawerPortal,
  DrawerOverlay,
  DrawerTrigger,
  DrawerClose,
  DrawerContent,
  DrawerHeader,
  DrawerFooter,
  DrawerTitle,
  DrawerDescription,
} from "@prototyperco/ui/components/drawer";
```
</component>

<component name="field" url="https://prototyper-ui.com/docs/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
```tsx
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field";
import { Input } from "@/components/ui/text-field";

export default function FieldDemo() {
  return (
    <Field>
      <FieldLabel>Email</FieldLabel>
      <Input placeholder="you@example.com" />
      <FieldDescription>We will never share your email.</FieldDescription>
    </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";
```

```tsx
<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

### Horizontal

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

export default function FieldHorizontal() {
  return (
    <Field orientation="horizontal">
      <FieldLabel>Username</FieldLabel>
      <Input placeholder="johndoe" />
    </Field>
  );
}
```

### Required

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

export default function FieldRequired() {
  return (
    <Field>
      <FieldLabel required>Full name</FieldLabel>
      <Input placeholder="Jane Doe" />
      <FieldDescription>Your legal full name.</FieldDescription>
    </Field>
  );
}
```

### Error

```tsx
import { Field, FieldError, FieldLabel } from "@/components/ui/field";
import { Input } from "@/components/ui/text-field";

export default function FieldErrorDemo() {
  return (
    <Field data-invalid="true">
      <FieldLabel>Email</FieldLabel>
      <Input placeholder="you@example.com" />
      <FieldError>Please enter a valid email address.</FieldError>
    </Field>
  );
}
```

### With Select

```tsx
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field";
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@/components/ui/select";

export default function FieldWithSelect() {
  return (
    <Field>
      <FieldLabel>Country</FieldLabel>
      <Select defaultValue="us">
        <SelectTrigger>
          <SelectValue />
        </SelectTrigger>
        <SelectContent>
          <SelectItem value="us">United States</SelectItem>
          <SelectItem value="uk">United Kingdom</SelectItem>
          <SelectItem value="de">Germany</SelectItem>
          <SelectItem value="fr">France</SelectItem>
          <SelectItem value="jp">Japan</SelectItem>
        </SelectContent>
      </Select>
      <FieldDescription>Select your country of residence.</FieldDescription>
    </Field>
  );
}
```

### With Checkbox

```tsx
import {
  Checkbox,
  CheckboxControl,
  CheckboxIndicator,
} from "@/components/ui/checkbox";
import { Field, FieldContent, FieldDescription } from "@/components/ui/field";

export default function FieldWithCheckbox() {
  return (
    <Field orientation="horizontal">
      <Checkbox>
        <CheckboxControl>
          <CheckboxIndicator />
        </CheckboxControl>
      </Checkbox>
      <FieldContent>
        <span className="text-sm font-medium leading-snug">
          Accept terms and conditions
        </span>
        <FieldDescription>
          You agree to our Terms of Service and Privacy Policy.
        </FieldDescription>
      </FieldContent>
    </Field>
  );
}
```

### Field Group

```tsx
import { Field, FieldGroup, FieldLabel } from "@/components/ui/field";
import { Input } from "@/components/ui/text-field";

export default function FieldGroupDemo() {
  return (
    <Field>
      <FieldLabel>Price</FieldLabel>
      <FieldGroup>
        <span className="text-muted-foreground pl-1 text-sm">$</span>
        <Input
          className="border-none shadow-none focus-visible:ring-0"
          placeholder="0.00"
        />
        <span className="text-muted-foreground pr-1 text-sm">USD</span>
      </FieldGroup>
    </Field>
  );
}
```

### Fieldset

```tsx
import {
  Field,
  FieldLabel,
  FieldLegend,
  FieldSeparator,
  FieldSet,
} from "@/components/ui/field";
import { Input } from "@/components/ui/text-field";

export default function FieldFieldset() {
  return (
    <FieldSet>
      <FieldLegend>Shipping Address</FieldLegend>
      <Field>
        <FieldLabel>Street</FieldLabel>
        <Input placeholder="123 Main St" />
      </Field>
      <FieldSeparator />
      <Field>
        <FieldLabel>City</FieldLabel>
        <Input placeholder="San Francisco" />
      </Field>
      <FieldSeparator />
      <Field>
        <FieldLabel>Zip code</FieldLabel>
        <Input placeholder="94102" />
      </Field>
    </FieldSet>
  );
}
```

## 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                      |
| `field-separator-content` | Text inside 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;
}

/* Make field groups pill-shaped */
[data-slot="field-group"] {
  @apply rounded-full;
}
```

```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. "responsive" switches from vertical to horizontal at the @md container breakpoint. |
| `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 |
| --- | --- | --- | --- |
| `required` | `boolean` | - | Displays a red asterisk (*) after the label text. |
| `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>`. Useful when the field does not contain a single focusable control.

| 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. Automatically hidden when the field is in an invalid state.

| 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 animated reveal and live-region semantics.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `errors` | `Array<{ message?: string } \| undefined>` | - | Array of error objects to display. Duplicate messages are deduplicated. Multiple errors render as a list. |
| `className` | `string` | - | Additional CSS classes. |
| `children` | `React.ReactNode` | - | Custom error content (overrides the errors prop). |

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

### FieldGroup

Styled container for grouping multiple inputs or addon elements into a single bordered row.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "ghost"` | `"default"` | Visual style. "default" shows a bordered, shadowed input container. "ghost" removes all styling. |
| `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. Useful in horizontal layouts to keep description and error stacked beside the control.

| 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. Automatically adjusts gap for checkbox-group and radio-group children.

| 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 with size variant support.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"legend" \| "label"` | `"legend"` | "legend" renders at base text size, "label" renders at small text size matching FieldLabel. |
| `className` | `string` | - | Additional CSS classes. |
| `children` | `React.ReactNode` | - | Legend content. |

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

### FieldSeparator

Visual separator between fields, optionally displaying centered text content.

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

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, propagating destructive text color to children.
- `data-disabled` is set when the field is disabled, and disabled styling propagates to child labels.
- `FieldLabel` with `required` adds a visual asterisk indicator.

## Full Component Source

```tsx
"use client";

export {
  Field,
  FieldLabel,
  FieldDescription,
  FieldError,
  FieldGroup,
  FieldLegend,
  FieldSeparator,
  FieldSet,
  FieldContent,
  FieldTitle,
} from "@prototyperco/ui/components/field";
```
</component>

<component name="fieldset" url="https://prototyper-ui.com/docs/components/fieldset">
# Fieldset
> A fieldset with accessible legend for grouping related form controls
URL: https://prototyper-ui.com/docs/components/fieldset
Base UI reference: https://base-ui.com/react/components/fieldset
```tsx
import {
  Checkbox,
  CheckboxControl,
  CheckboxIndicator,
} from "@/components/ui/checkbox";
import { Fieldset, FieldsetLegend } from "@/components/ui/fieldset";

export default function FieldsetDemo() {
  return (
    <Fieldset>
      <FieldsetLegend>Notifications</FieldsetLegend>
      <Checkbox name="email" defaultChecked>
        <CheckboxControl>
          <CheckboxIndicator />
        </CheckboxControl>
        Email notifications
      </Checkbox>
      <Checkbox name="sms">
        <CheckboxControl>
          <CheckboxIndicator />
        </CheckboxControl>
        SMS notifications
      </Checkbox>
      <Checkbox name="push">
        <CheckboxControl>
          <CheckboxIndicator />
        </CheckboxControl>
        Push notifications
      </Checkbox>
    </Fieldset>
  );
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/fieldset.tsx`

## Usage

```tsx
import { Fieldset, FieldsetLegend } from "@/components/ui/fieldset";

<Fieldset>
  <FieldsetLegend>Preferences</FieldsetLegend>
  {/* form controls */}
</Fieldset>;
```

## Anatomy

```tsx
<Fieldset>
  <FieldsetLegend />
  {/* Field, Checkbox, RadioGroup, or other controls */}
</Fieldset>
```

| Sub-component    | `data-slot`       | Purpose                                          | Required |
| ---------------- | ----------------- | ------------------------------------------------ | -------- |
| `Fieldset`       | `fieldset`        | Root container, renders `<fieldset>` with ARIA   | Yes      |
| `FieldsetLegend` | `fieldset-legend` | Accessible legend, renders `<div>` with ARIA tie | Yes      |

## Examples

### Disabled

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

export default function FieldsetDisabled() {
  return (
    <Fieldset disabled>
      <FieldsetLegend>Notifications (disabled)</FieldsetLegend>
      <Checkbox name="email" defaultChecked>
        <CheckboxControl>
          <CheckboxIndicator />
        </CheckboxControl>
        Email notifications
      </Checkbox>
      <Checkbox name="sms">
        <CheckboxControl>
          <CheckboxIndicator />
        </CheckboxControl>
        SMS notifications
      </Checkbox>
    </Fieldset>
  );
}
```

### With Fields

```tsx
import { Field, FieldLabel, FieldDescription } from "@/components/ui/field";
import { Fieldset, FieldsetLegend } from "@/components/ui/fieldset";
import { Input } from "@/components/ui/input";

export default function FieldsetWithFields() {
  return (
    <Fieldset>
      <FieldsetLegend>Shipping Address</FieldsetLegend>
      <Field>
        <FieldLabel>Street</FieldLabel>
        <Input name="street" placeholder="123 Main St" />
      </Field>
      <Field>
        <FieldLabel>City</FieldLabel>
        <Input name="city" placeholder="San Francisco" />
      </Field>
      <Field>
        <FieldLabel>ZIP Code</FieldLabel>
        <Input name="zip" placeholder="94102" />
        <FieldDescription>5-digit ZIP code.</FieldDescription>
      </Field>
    </Fieldset>
  );
}
```

## Styling

### Data Slots

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

| Slot name         | Element                 |
| ----------------- | ----------------------- |
| `fieldset`        | Root fieldset container |
| `fieldset-legend` | Legend text             |

### Customization Examples

```css
/* Tighter fieldset spacing */
[data-slot="fieldset"] {
  @apply gap-4;
}

/* Style the legend as a smaller label */
[data-slot="fieldset-legend"] {
  @apply text-sm text-muted-foreground;
}
```

```tsx
{
  /* Label-sized legend variant */
}
<Fieldset>
  <FieldsetLegend variant="label">Settings</FieldsetLegend>
  {/* ... */}
</Fieldset>;
```

## API Reference

### Fieldset

Root container that groups related form controls. Renders a `<fieldset>` element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether all controls within the fieldset are disabled |
| `className` | `string` | - | Additional CSS classes |

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

### FieldsetLegend

Accessible legend that is automatically associated with the fieldset. Renders a `<div>` element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"legend" \| "label"` | `"legend"` | Size variant — "legend" for section headings, "label" for smaller inline labels |
| `className` | `string` | - | Additional CSS classes |

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

## Accessibility

### ARIA Attributes

- `Fieldset` renders a `<fieldset>` element with native grouping semantics.
- `FieldsetLegend` renders a `<div>` but is automatically associated with the fieldset via `aria-labelledby`.
- When `disabled` is set on the fieldset, all nested controls inherit the disabled state.
- Screen readers announce the legend as the group label when navigating into the fieldset.

## Full Component Source

```tsx
"use client";

export { Fieldset, FieldsetLegend } from "@prototyperco/ui/components/fieldset";
```
</component>

<component name="form" url="https://prototyper-ui.com/docs/components/form">
# Form
> form with consolidated error handling on Base UI
URL: https://prototyper-ui.com/docs/components/form
Base UI reference: https://base-ui.com/react/components/form
```tsx
"use client";

import { Field, FieldLabel, FieldDescription } from "@/components/ui/field";
import { Form } from "@/components/ui/form";
import { Input } from "@/components/ui/input";
import { Button } from "@/components/ui/button";

export default function FormDemo() {
  return (
    <Form
      onFormSubmit={(formValues) => {
        alert(JSON.stringify(formValues, null, 2));
      }}
      className="w-full max-w-sm"
    >
      <Field>
        <FieldLabel>Name</FieldLabel>
        <Input name="name" placeholder="Enter your name" required />
      </Field>
      <Field>
        <FieldLabel>Email</FieldLabel>
        <Input
          name="email"
          type="email"
          placeholder="Enter your email"
          required
        />
        <FieldDescription>We will never share your email.</FieldDescription>
      </Field>
      <Button type="submit">Submit</Button>
    </Form>
  );
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/form.tsx`

## Usage

```tsx
import { Form } from "@/components/ui/form";

<Form onFormSubmit={(formValues) => console.log(formValues)}>
  {/* Field components */}
  <button type="submit">Submit</button>
</Form>;
```

## Examples

### Server Errors

```tsx
"use client";

import { useState } from "react";
import { Field, FieldLabel, FieldError } from "@/components/ui/field";
import { Form } from "@/components/ui/form";
import { Input } from "@/components/ui/input";
import { Button } from "@/components/ui/button";

export default function FormServerErrors() {
  const [errors, setErrors] = useState<Record<string, string>>({});

  return (
    <Form
      errors={errors}
      onFormSubmit={(formValues) => {
        const newErrors: Record<string, string> = {};
        if (!formValues.username) {
          newErrors.username = "Username is required.";
        }
        if (!formValues.password) {
          newErrors.password = "Password is required.";
        } else if (formValues.password.length < 8) {
          newErrors.password = "Password must be at least 8 characters.";
        }
        setErrors(newErrors);
      }}
      className="w-full max-w-sm"
    >
      <Field>
        <FieldLabel>Username</FieldLabel>
        <Input name="username" placeholder="Choose a username" />
        <FieldError />
      </Field>
      <Field>
        <FieldLabel>Password</FieldLabel>
        <Input
          name="password"
          type="password"
          placeholder="Choose a password"
        />
        <FieldError />
      </Field>
      <Button type="submit">Create Account</Button>
    </Form>
  );
}
```

### Validation Modes

```tsx
"use client";

import { Field, FieldLabel, FieldError } from "@/components/ui/field";
import { Form } from "@/components/ui/form";
import { Input } from "@/components/ui/input";
import { Button } from "@/components/ui/button";

export default function FormValidationModes() {
  return (
    <Form
      validationMode="onBlur"
      onFormSubmit={(formValues) => {
        alert(JSON.stringify(formValues, null, 2));
      }}
      className="w-full max-w-sm"
    >
      <Field>
        <FieldLabel>Email</FieldLabel>
        <Input
          name="email"
          type="email"
          placeholder="Validates on blur"
          required
        />
        <FieldError />
      </Field>
      <Field>
        <FieldLabel>Website</FieldLabel>
        <Input
          name="website"
          type="url"
          placeholder="https://example.com"
          required
        />
        <FieldError />
      </Field>
      <Button type="submit">Submit</Button>
    </Form>
  );
}
```

## Styling

### Data Slots

Use `data-slot` attributes to target the form:

| Slot name | Element           |
| --------- | ----------------- |
| `form`    | Root form element |

### Customization Examples

```css
/* Custom form layout */
[data-slot="form"] {
  @apply gap-4;
}
```

```tsx
{
  /* Override gap spacing */
}
<Form className="gap-8">{/* ... */}</Form>;
```

## API Reference

### Form

Root form element with consolidated error handling. Renders a `<form>` element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `errors` | `Record<string, string \| string[]>` | - | Validation errors returned externally (e.g. from server). Keys correspond to field `name` attributes. |
| `validationMode` | `"onSubmit" \| "onBlur" \| "onChange"` | `"onSubmit"` | When the form fields should be validated |
| `onFormSubmit` | `(formValues: FormValues, eventDetails: SubmitEventDetails) => void` | - | Event handler called when the form is submitted. preventDefault is called automatically. |
| `actionsRef` | `React.RefObject<{ validate: (fieldName?: string) => void } \| null>` | - | Ref to imperative actions. Call validate() to trigger validation programmatically. |
| `className` | `string` | - | Additional CSS classes |

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

## Accessibility

### ARIA Attributes

- Renders a native `<form>` element with proper form semantics.
- Error messages are associated with fields via `aria-describedby`.
- `aria-invalid` is set on fields with validation errors.
- The `errors` prop triggers `aria-errormessage` associations on matching fields.

## Full Component Source

```tsx
"use client";

export { Form } from "@prototyperco/ui/components/form";
```
</component>

<component name="form-field" url="https://prototyper-ui.com/docs/components/form-field">
# FormField
> A react-hook-form helper that wires Field, label, description, and error to a Controller in one component
URL: https://prototyper-ui.com/docs/components/form-field
```tsx
"use client";

import { useForm, FormProvider } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";
import { FormField } from "@/components/ui/form-field";
import { Input } from "@/components/ui/input";
import { Textarea } from "@/components/ui/textarea";
import { Button } from "@/components/ui/button";

const schema = z.object({
  name: z.string().min(1, "Name is required"),
  email: z.string().email("Please enter a valid email"),
  message: z.string().min(10, "Message must be at least 10 characters"),
});

type FormValues = z.infer<typeof schema>;

export default function FormFieldDemo() {
  const form = useForm<FormValues>({
    resolver: zodResolver(schema),
    defaultValues: { name: "", email: "", message: "" },
  });

  const onSubmit = (data: FormValues) => {
    alert(JSON.stringify(data, null, 2));
  };

  return (
    <FormProvider {...form}>
      <form
        onSubmit={form.handleSubmit(onSubmit)}
        className="w-full max-w-sm space-y-4"
      >
        <FormField name="name" label="Name" required>
          <Input placeholder="Jane Doe" />
        </FormField>

        <FormField name="email" label="Email" required>
          <Input type="email" placeholder="jane@example.com" />
        </FormField>

        <FormField
          name="message"
          label="Message"
          description="Tell us what you need help with."
        >
          <Textarea placeholder="Your message..." />
        </FormField>

        <Button type="submit">Submit</Button>
      </form>
    </FormProvider>
  );
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/form-field.tsx`

> **Peer dependency:** This component requires `react-hook-form`. Install it alongside:
>
> ```bash
> npm install react-hook-form @hookform/resolvers zod
> ```

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

## Usage

```tsx
import { useForm, FormProvider } from "react-hook-form"
import { FormField } from "@/components/ui/form-field"
import { Input } from "@/components/ui/input"

const form = useForm({ defaultValues: { email: "" } })

<FormProvider {...form}>
  <form onSubmit={form.handleSubmit(onSubmit)}>
    <FormField name="email" label="Email" required>
      <Input type="email" placeholder="you@example.com" />
    </FormField>
  </form>
</FormProvider>
```

`FormField` uses `Controller` + `useFormContext` internally, so it must be rendered inside a `<FormProvider>`. It auto-wires `value`, `onChange`, `onBlur`, and `ref` to the child input via `cloneElement`.

### When to use FormField vs raw Field

| Use `FormField`                       | Use raw `Field` + `Controller`                          |
| ------------------------------------- | ------------------------------------------------------- |
| Standard text inputs, textareas       | Select, NumberField, Checkbox, Switch, RadioGroup       |
| Quick forms with minimal boilerplate  | Components that use `onValueChange` / `onCheckedChange` |
| Inputs accepting `value` + `onChange` | Custom controlled components                            |

For components with non-standard change handlers, use `Controller` directly with `Field` as shown in the [Forms guide](/docs/forms#react-hook-form-integration).

## Examples

### Validation

```tsx
"use client";

import { useForm, FormProvider } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";
import { FormField } from "@/components/ui/form-field";
import { Input } from "@/components/ui/input";
import { Button } from "@/components/ui/button";

const schema = z
  .object({
    username: z
      .string()
      .min(3, "Username must be at least 3 characters")
      .max(20, "Username must be at most 20 characters")
      .regex(
        /^[a-z0-9_]+$/,
        "Only lowercase letters, numbers, and underscores",
      ),
    email: z.string().email("Please enter a valid email address"),
    password: z
      .string()
      .min(8, "Password must be at least 8 characters")
      .regex(/[A-Z]/, "Must contain at least one uppercase letter")
      .regex(/[0-9]/, "Must contain at least one number"),
    confirmPassword: z.string(),
  })
  .refine((data) => data.password === data.confirmPassword, {
    message: "Passwords do not match",
    path: ["confirmPassword"],
  });

type FormValues = z.infer<typeof schema>;

export default function FormFieldValidation() {
  const form = useForm<FormValues>({
    resolver: zodResolver(schema),
    defaultValues: {
      username: "",
      email: "",
      password: "",
      confirmPassword: "",
    },
  });

  const onSubmit = (data: FormValues) => {
    alert(JSON.stringify(data, null, 2));
  };

  return (
    <FormProvider {...form}>
      <form
        onSubmit={form.handleSubmit(onSubmit)}
        className="w-full max-w-sm space-y-4"
      >
        <FormField
          name="username"
          label="Username"
          description="Lowercase letters, numbers, and underscores only."
          required
        >
          <Input placeholder="jane_doe" />
        </FormField>

        <FormField name="email" label="Email" required>
          <Input type="email" placeholder="jane@example.com" />
        </FormField>

        <FormField name="password" label="Password" required>
          <Input type="password" placeholder="At least 8 characters" />
        </FormField>

        <FormField name="confirmPassword" label="Confirm Password" required>
          <Input type="password" placeholder="Repeat your password" />
        </FormField>

        <Button type="submit">Create Account</Button>
      </form>
    </FormProvider>
  );
}
```

### All Input Types

```tsx
"use client";

import * as React from "react";
import { useForm, FormProvider, Controller } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";
import { FormField } from "@/components/ui/form-field";
import { Field, FieldLabel, FieldError } from "@/components/ui/field";
import { Input } from "@/components/ui/input";
import { Textarea } from "@/components/ui/textarea";
import {
  Select,
  SelectTrigger,
  SelectValue,
  SelectContent,
  SelectItem,
} from "@/components/ui/select";
import {
  NumberField,
  NumberFieldGroup,
  NumberFieldInput,
  NumberFieldSteppers,
} from "@/components/ui/number-field";
import {
  Checkbox,
  CheckboxControl,
  CheckboxIndicator,
} from "@/components/ui/checkbox";
import { Switch, SwitchTrack, SwitchThumb } from "@/components/ui/switch";
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";
import { Button } from "@/components/ui/button";

const schema = z.object({
  name: z.string().min(1, "Name is required"),
  bio: z.string().optional(),
  role: z.string().min(1, "Please select a role"),
  age: z.number().min(18, "Must be at least 18"),
  terms: z.boolean().refine((v) => v, "You must accept the terms"),
  notifications: z.boolean().optional(),
  plan: z.string().min(1, "Please select a plan"),
});

type FormValues = z.infer<typeof schema>;

export default function FormFieldAllInputs() {
  const form = useForm<FormValues>({
    resolver: zodResolver(schema),
    defaultValues: {
      name: "",
      bio: "",
      role: "",
      age: 25,
      terms: false,
      notifications: true,
      plan: "",
    },
  });

  const onSubmit = (data: FormValues) => {
    alert(JSON.stringify(data, null, 2));
  };

  return (
    <FormProvider {...form}>
      <form
        onSubmit={form.handleSubmit(onSubmit)}
        className="w-full max-w-sm space-y-4"
      >
        {/* TextField — works directly with FormField */}
        <FormField name="name" label="Name" required>
          <Input placeholder="Jane Doe" />
        </FormField>

        {/* Textarea — works directly with FormField */}
        <FormField name="bio" label="Bio" description="Optional short bio.">
          <Textarea placeholder="Tell us about yourself..." />
        </FormField>

        {/* Select — use Controller for onValueChange mapping */}
        <Controller
          name="role"
          control={form.control}
          render={({ field, fieldState }) => (
            <Field data-invalid={fieldState.error ? true : undefined}>
              <FieldLabel required>Role</FieldLabel>
              <Select value={field.value} onValueChange={field.onChange}>
                <SelectTrigger>
                  <SelectValue placeholder="Select a role" />
                </SelectTrigger>
                <SelectContent>
                  <SelectItem value="developer">Developer</SelectItem>
                  <SelectItem value="designer">Designer</SelectItem>
                  <SelectItem value="manager">Manager</SelectItem>
                </SelectContent>
              </Select>
              <FieldError>{fieldState.error?.message}</FieldError>
            </Field>
          )}
        />

        {/* NumberField — use Controller for onValueChange mapping */}
        <Controller
          name="age"
          control={form.control}
          render={({ field, fieldState }) => (
            <NumberField
              value={field.value}
              onValueChange={field.onChange}
              min={0}
              max={120}
            >
              <FieldLabel required>Age</FieldLabel>
              <NumberFieldGroup>
                <NumberFieldInput />
                <NumberFieldSteppers />
              </NumberFieldGroup>
              <FieldError>{fieldState.error?.message}</FieldError>
            </NumberField>
          )}
        />

        {/* Checkbox — use Controller for checked/onCheckedChange */}
        <Controller
          name="terms"
          control={form.control}
          render={({ field, fieldState }) => (
            <Field data-invalid={fieldState.error ? true : undefined}>
              <Checkbox checked={field.value} onCheckedChange={field.onChange}>
                <CheckboxControl>
                  <CheckboxIndicator />
                </CheckboxControl>
                I accept the terms and conditions
              </Checkbox>
              <FieldError>{fieldState.error?.message}</FieldError>
            </Field>
          )}
        />

        {/* Switch — use Controller for checked/onCheckedChange */}
        <Controller
          name="notifications"
          control={form.control}
          render={({ field }) => (
            <Field>
              <FieldLabel>Email Notifications</FieldLabel>
              <Switch checked={field.value} onCheckedChange={field.onChange}>
                <SwitchTrack>
                  <SwitchThumb />
                </SwitchTrack>
              </Switch>
            </Field>
          )}
        />

        {/* RadioGroup — use Controller for onValueChange */}
        <Controller
          name="plan"
          control={form.control}
          render={({ field, fieldState }) => (
            <Field data-invalid={fieldState.error ? true : undefined}>
              <FieldLabel required>Plan</FieldLabel>
              <RadioGroup value={field.value} onValueChange={field.onChange}>
                <RadioGroupItem value="free">Free</RadioGroupItem>
                <RadioGroupItem value="pro">Pro</RadioGroupItem>
                <RadioGroupItem value="enterprise">Enterprise</RadioGroupItem>
              </RadioGroup>
              <FieldError>{fieldState.error?.message}</FieldError>
            </Field>
          )}
        />

        <Button type="submit">Submit</Button>
      </form>
    </FormProvider>
  );
}
```

### Dynamic Fields

```tsx
"use client";

import { useForm, FormProvider, useFieldArray } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";
import { FormField } from "@/components/ui/form-field";
import { Input } from "@/components/ui/input";
import { Button } from "@/components/ui/button";
import { Plus, Trash2 } from "lucide-react";

const schema = z.object({
  teamName: z.string().min(1, "Team name is required"),
  members: z
    .array(
      z.object({
        name: z.string().min(1, "Name is required"),
        email: z.string().email("Invalid email"),
      }),
    )
    .min(1, "Add at least one member"),
});

type FormValues = z.infer<typeof schema>;

export default function FormFieldDynamic() {
  const form = useForm<FormValues>({
    resolver: zodResolver(schema),
    defaultValues: {
      teamName: "",
      members: [{ name: "", email: "" }],
    },
  });

  const { fields, append, remove } = useFieldArray({
    control: form.control,
    name: "members",
  });

  const onSubmit = (data: FormValues) => {
    alert(JSON.stringify(data, null, 2));
  };

  return (
    <FormProvider {...form}>
      <form
        onSubmit={form.handleSubmit(onSubmit)}
        className="w-full max-w-sm space-y-6"
      >
        <FormField name="teamName" label="Team Name" required>
          <Input placeholder="Engineering" />
        </FormField>

        <div className="space-y-4">
          <p className="text-sm font-medium">Team Members</p>

          {fields.map((field, index) => (
            <div key={field.id} className="space-y-3 rounded-md border p-3">
              <div className="flex items-center justify-between">
                <span className="text-muted-foreground text-xs">
                  Member {index + 1}
                </span>
                {fields.length > 1 && (
                  <Button
                    type="button"
                    variant="ghost"
                    size="icon-xs"
                    onClick={() => remove(index)}
                  >
                    <Trash2 className="size-3.5" />
                  </Button>
                )}
              </div>

              <FormField name={`members.${index}.name`} label="Name" required>
                <Input placeholder="Jane Doe" />
              </FormField>

              <FormField name={`members.${index}.email`} label="Email" required>
                <Input type="email" placeholder="jane@example.com" />
              </FormField>
            </div>
          ))}

          <Button
            type="button"
            variant="outline"
            size="sm"
            className="w-full"
            onClick={() => append({ name: "", email: "" })}
          >
            <Plus className="mr-1.5 size-3.5" />
            Add Member
          </Button>
        </div>

        <Button type="submit">Create Team</Button>
      </form>
    </FormProvider>
  );
}
```

### Multi-Step Form

```tsx
"use client";

import * as React from "react";
import { useForm, FormProvider } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";
import { FormField } from "@/components/ui/form-field";
import { Input } from "@/components/ui/input";
import { Textarea } from "@/components/ui/textarea";
import { Button } from "@/components/ui/button";

const step1Schema = z.object({
  firstName: z.string().min(1, "First name is required"),
  lastName: z.string().min(1, "Last name is required"),
  email: z.string().email("Please enter a valid email"),
});

const step2Schema = z.object({
  company: z.string().min(1, "Company is required"),
  role: z.string().min(1, "Role is required"),
});

const step3Schema = z.object({
  message: z.string().min(10, "Message must be at least 10 characters"),
});

const fullSchema = step1Schema.merge(step2Schema).merge(step3Schema);
type FormValues = z.infer<typeof fullSchema>;

const stepSchemas = [step1Schema, step2Schema, step3Schema] as const;
const stepFields: (keyof FormValues)[][] = [
  ["firstName", "lastName", "email"],
  ["company", "role"],
  ["message"],
];

export default function FormFieldMultiStep() {
  const [step, setStep] = React.useState(0);

  const form = useForm<FormValues>({
    resolver: zodResolver(fullSchema),
    defaultValues: {
      firstName: "",
      lastName: "",
      email: "",
      company: "",
      role: "",
      message: "",
    },
    mode: "onTouched",
  });

  const goNext = async () => {
    const fields = stepFields[step];
    const valid = await form.trigger(fields);
    if (valid) setStep((s) => s + 1);
  };

  const goBack = () => setStep((s) => s - 1);

  const onSubmit = (data: FormValues) => {
    alert(JSON.stringify(data, null, 2));
  };

  return (
    <FormProvider {...form}>
      <form
        onSubmit={form.handleSubmit(onSubmit)}
        className="w-full max-w-sm space-y-4"
      >
        <div className="flex gap-1.5">
          {stepSchemas.map((_, i) => (
            <div
              key={i}
              className={`h-1 flex-1 rounded-full transition-colors ${
                i <= step ? "bg-primary" : "bg-muted"
              }`}
            />
          ))}
        </div>

        <p className="text-muted-foreground text-sm">
          Step {step + 1} of {stepSchemas.length}
        </p>

        {step === 0 && (
          <div className="space-y-4">
            <FormField name="firstName" label="First Name" required>
              <Input placeholder="Jane" />
            </FormField>
            <FormField name="lastName" label="Last Name" required>
              <Input placeholder="Doe" />
            </FormField>
            <FormField name="email" label="Email" required>
              <Input type="email" placeholder="jane@example.com" />
            </FormField>
          </div>
        )}

        {step === 1 && (
          <div className="space-y-4">
            <FormField name="company" label="Company" required>
              <Input placeholder="Acme Inc." />
            </FormField>
            <FormField name="role" label="Role" required>
              <Input placeholder="Software Engineer" />
            </FormField>
          </div>
        )}

        {step === 2 && (
          <div className="space-y-4">
            <FormField
              name="message"
              label="Message"
              description="Tell us about your project."
            >
              <Textarea placeholder="Describe your goals..." />
            </FormField>
          </div>
        )}

        <div className="flex gap-2">
          {step > 0 && (
            <Button type="button" variant="outline" onClick={goBack}>
              Back
            </Button>
          )}
          {step < stepSchemas.length - 1 ? (
            <Button type="button" onClick={goNext}>
              Continue
            </Button>
          ) : (
            <Button type="submit">Submit</Button>
          )}
        </div>
      </form>
    </FormProvider>
  );
}
```

## Styling

### Data Slots

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

| Slot name           | Element                 |
| ------------------- | ----------------------- |
| `form-field`        | Root `Field` wrapper    |
| `field-label`       | Label element           |
| `field-description` | Description paragraph   |
| `field-error`       | Error message container |

### Customization Examples

```css
/* Increase spacing between form fields */
[data-slot="form-field"] {
  @apply gap-2;
}
```

```tsx
{
  /* Override width via className */
}
<FormField name="email" label="Email" className="max-w-xs">
  <Input />
</FormField>;
```

## API Reference

### FormField

A helper component that wires a `Controller` to `Field` + `FieldLabel` + `FieldDescription` + `FieldError`.

| Prop          | Type                 | Default | Description                              |
| ------------- | -------------------- | ------- | ---------------------------------------- |
| `name`        | `string`             | -       | Field name matching the form schema      |
| `label`       | `string`             | -       | Label text displayed above the input     |
| `description` | `string`             | -       | Help text displayed below the label      |
| `required`    | `boolean`            | -       | Shows a required indicator on the label  |
| `className`   | `string`             | -       | Additional CSS classes on the root Field |
| `children`    | `React.ReactElement` | -       | The input component to wire up           |

## Accessibility

### Keyboard Interactions

| Key   | Action                                    |
| ----- | ----------------------------------------- |
| `Tab` | Moves focus to the input within the field |

### ARIA Attributes

- The `Field` wrapper renders with `role="group"`.
- `FieldLabel` is associated with the input via Base UI's label mechanism.
- `FieldError` renders with `role="alert"` and `aria-live="polite"` for screen reader announcements.
- When `invalid` is true, `data-invalid` is set on the field for styling hooks.

## Full Component Source

```tsx
"use client";

import * as React from "react";
import {
  Controller,
  useFormContext,
  type FieldValues,
  type Path,
  type FieldError as RHFFieldError,
} from "react-hook-form";

import { cn } from "@/lib/utils";
import {
  Field,
  FieldLabel,
  FieldDescription,
  FieldError,
} from "@/components/ui/field";

interface FormFieldProps<T extends FieldValues = FieldValues> {
  name: Path<T>;
  label: string;
  description?: string;
  required?: boolean;
  className?: string;
  children: React.ReactElement;
}

function FormField<T extends FieldValues = FieldValues>({
  name,
  label,
  description,
  required,
  className,
  children,
}: FormFieldProps<T>) {
  const { control } = useFormContext<T>();

  return (
    <Controller
      name={name}
      control={control}
      render={({ field, fieldState }) => {
        const error = fieldState.error as RHFFieldError | undefined;
        return (
          <Field
            data-slot="form-field"
            data-invalid={error ? true : undefined}
            className={cn(className)}
          >
            <FieldLabel required={required}>{label}</FieldLabel>
            {description && <FieldDescription>{description}</FieldDescription>}
            {React.cloneElement(children, { ...field })}
            <FieldError>{error?.message}</FieldError>
          </Field>
        );
      }}
    />
  );
}

export { FormField };

export type { FormFieldProps };
```
</component>

<component name="input" url="https://prototyper-ui.com/docs/components/input">
# Input
> a styled text input field built on Base UI
URL: https://prototyper-ui.com/docs/components/input
Base UI reference: https://base-ui.com/react/components/input
```tsx
import { Input } from "@/components/ui/input";

export default function InputDemo() {
  return <Input type="email" placeholder="Email" />;
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/input.tsx`

## Usage

```tsx
import { Input } from "@/components/ui/input";

<Input type="email" placeholder="Email" />;
```

## Styling

### Data Slots

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

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

### Customization Examples

```css
/* Make all inputs taller */
[data-slot="input"] {
  @apply h-12 text-lg;
}
```

```tsx
{
  /* Override styles via className */
}
<Input className="rounded-full px-5" placeholder="Pill input" />;
```

## API Reference

### Input

A styled text input built on Base UI `Input`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `string` | - | HTML input type (e.g. "text", "email", "password") |
| `className` | `string` | - | Additional CSS classes |

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

## Accessibility

### Keyboard Interactions

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

### ARIA Attributes

- Renders as a native `<input>` element via Base UI `Input`.
- `aria-invalid` styling is applied when the input has validation errors.
- Pair with a `<label>` or `aria-label` to ensure the input is accessible to screen readers.

## Compose

This component is available in [`@prototyperco/compose`](/docs/compose).

### Catalog Definition

```typescript title="input.catalog.ts"
import { z } from "zod";
import { defineComponent } from "@prototyperco/compose/catalog";

export default defineComponent({
  description: "A text input field for user data entry",
  props: z.object({
    label: z.string().optional().describe("Label displayed above the input"),
    name: z.string().optional().describe("Field name for form submission"),
    placeholder: z.string().optional().describe("Placeholder text"),
    type: z
      .enum(["text", "email", "password", "number", "search", "tel", "url"])
      .optional()
      .describe("Input type"),
    disabled: z.boolean().optional().describe("Whether the input is disabled"),
    readOnly: z.boolean().optional().describe("Whether the input is read-only"),
    value: z.string().optional().describe("Controlled input value"),
  }),
  events: ["change", "focus", "blur", "submit"],
  example: { label: "Name", placeholder: "Enter your name...", type: "text" },
});
```

### Example Spec

```json
{
  "root": "nameInput",
  "elements": {
    "nameInput": {
      "type": "Input",
      "props": {
        "label": "Name",
        "placeholder": "Enter your name...",
        "type": "text"
      },
      "$bindState": { "path": "/name", "event": "change" }
    }
  }
}
```

Learn more in the [Compose documentation](/docs/compose).

## Full Component Source

```tsx
"use client";

export { Input } from "@prototyperco/ui/components/input";
```
</component>

<component name="input-group" url="https://prototyper-ui.com/docs/components/input-group">
# InputGroup
> a composable input group with addons, buttons, and text
URL: https://prototyper-ui.com/docs/components/input-group
```tsx
import { ArrowRight } from "lucide-react";

import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupInput,
} from "@/components/ui/input-group";

export default function InputGroupDemo() {
  return (
    <InputGroup className="max-w-sm">
      <InputGroupInput placeholder="Enter your email" />
      <InputGroupAddon align="inline-end">
        <InputGroupButton size="xs">
          Subscribe
          <ArrowRight />
        </InputGroupButton>
      </InputGroupAddon>
    </InputGroup>
  );
}
```

## Installation

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

This will add the following files to your project:

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

> **Note:** This component depends on [Button](/docs/components/button), [Input](/docs/components/input), and Textarea. They will be installed automatically.

## Usage

```tsx
import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupInput,
} from "@/components/ui/input-group";

<InputGroup>
  <InputGroupInput placeholder="Search..." />
  <InputGroupAddon align="inline-end">
    <InputGroupButton>Go</InputGroupButton>
  </InputGroupAddon>
</InputGroup>;
```

## Anatomy

```tsx
<InputGroup>
  <InputGroupAddon>
    <InputGroupText />
    <InputGroupButton />
  </InputGroupAddon>
  <InputGroupInput />
</InputGroup>
```

Or with a textarea:

```tsx
<InputGroup>
  <InputGroupAddon>
    <InputGroupText />
  </InputGroupAddon>
  <InputGroupTextarea />
</InputGroup>
```

| Sub-component        | `data-slot`           | Purpose                                          | Required |
| -------------------- | --------------------- | ------------------------------------------------ | -------- |
| `InputGroup`         | `input-group`         | Root wrapper, provides group styling context     | Yes      |
| `InputGroupAddon`    | `input-group-addon`   | Container for icons, text, buttons, or kbd hints | No       |
| `InputGroupButton`   | -                     | A compact button styled for use inside the group | No       |
| `InputGroupText`     | -                     | Inline text or icon container                    | No       |
| `InputGroupInput`    | `input-group-control` | Single-line text input (borderless)              | Yes\*    |
| `InputGroupTextarea` | `input-group-control` | Multi-line textarea (borderless)                 | Yes\*    |

\* Use either `InputGroupInput` or `InputGroupTextarea`, not both.

## Styling

### Data Slots

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

| Slot name             | Element                          |
| --------------------- | -------------------------------- |
| `input-group`         | Root wrapper `<div>`             |
| `input-group-addon`   | Addon container (icons, buttons) |
| `input-group-control` | The input or textarea element    |

### Customization Examples

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

/* Style addons */
[data-slot="input-group-addon"] {
  @apply text-foreground;
}
```

```tsx
{
  /* Override styles via className */
}
<InputGroup className="rounded-full">
  <InputGroupInput placeholder="Pill input group" />
</InputGroup>;
```

## API Reference

### InputGroup

Root wrapper that provides grouped styling and focus management.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Group content (addons, input, buttons) |

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

### InputGroupAddon

Container for icons, text, buttons, or keyboard shortcut hints.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"inline-start" \| "inline-end" \| "block-start" \| "block-end"` | `"inline-start"` | Position of the addon relative to the input |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Addon content (icons, text, buttons) |

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

### InputGroupButton

A compact button styled for use inside the input group. Extends [Button](/docs/components/button) props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"xs" \| "sm" \| "icon-xs" \| "icon-sm"` | `"xs"` | Size of the button |
| `variant` | `ButtonProps["variant"]` | `"ghost"` | Visual style variant (from Button) |
| `type` | `"button" \| "submit" \| "reset"` | `"button"` | HTML button type |
| `className` | `string` | - | Additional CSS classes |

All [Button](/docs/components/button) props (except `size` and `type`) are forwarded via `...props`.

### InputGroupText

Inline text or icon container for display content inside the group.

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

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

### InputGroupInput

A borderless single-line input styled for use inside the group. Built on [Input](/docs/components/input).

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

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

### InputGroupTextarea

A borderless multi-line textarea styled for use inside the group. Built on Textarea.

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

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

## Accessibility

### Keyboard Interactions

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

### ARIA Attributes

- `InputGroup` renders with `role="group"` to associate the input with its addons.
- `InputGroupAddon` renders with `role="group"` for semantic grouping.
- Clicking an addon area focuses the input for better usability.
- Pair with a `<label>` or `aria-label` on the input to ensure accessibility.

## Full Component Source

```tsx
"use client";

export {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupText,
  InputGroupInput,
  InputGroupTextarea,
} from "@prototyperco/ui/components/input-group";
```
</component>

<component name="label" url="https://prototyper-ui.com/docs/components/label">
# Label
> a form label with disabled and invalid state styling
URL: https://prototyper-ui.com/docs/components/label
Label renders a styled native `<label>` element for form controls. It picks up disabled and invalid state from a surrounding `Field` automatically, so you rarely have to wire styling by hand — the label dims when the input is disabled and turns red when the field is marked invalid. Use it for every form input you ship, both for accessibility and because users rely on visible labels far more than placeholder text alone.

```tsx
import { Label } from "@/components/ui/label";

export default function LabelDemo() {
  return <Label>Email address</Label>;
}
```

### When to use

- Any time a form control needs a visible, persistent name — inputs, selects, switches, checkboxes, radio groups.
- When you want disabled and invalid styling to flow from a parent `Field` without writing conditional class names.
- When you need a clickable target that focuses or toggles the associated control, since the native `<label>` element handles that for free.

Avoid using `Label` purely as decorative text — for headings, callouts, or section titles, reach for a semantic heading element instead so screen readers do not announce it as a form label.

## Installation

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

This will add the following files to your project:

- `components/ui/label.tsx`

## Usage

```tsx
import { Label } from "@/components/ui/label";
```

```tsx
<Label>Email address</Label>
```

## Examples

### With Input

```tsx
import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";

export default function LabelWithInput() {
  return (
    <div className="grid w-full max-w-sm gap-1.5">
      <Label htmlFor="email">Email</Label>
      <Input type="email" id="email" placeholder="you@example.com" />
    </div>
  );
}
```

## Styling

### Data Slots

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

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

### Customization Examples

```css
/* Make all labels uppercase */
[data-slot="label"] {
  @apply text-xs uppercase tracking-wide;
}
```

```tsx
<Label className="text-base font-semibold">Custom label</Label>
```

## API Reference

### Label

A styled `<label>` element for form controls.

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

All standard `label` element props are forwarded via `...props`.

## Accessibility

### Keyboard Interactions

Label is a non-interactive display element and does not have keyboard interactions. Clicking a label focuses or activates its associated form control via the `htmlFor` attribute or nesting.

### ARIA Attributes

- Renders as a native `<label>` element, so assistive technology announces it as the accessible name of the associated control automatically.
- Associate with a form control either by setting `htmlFor` to the control's `id`, or by nesting the control inside the label. Either pattern works; pick the one that fits your layout.
- Automatically receives `data-disabled` and `data-invalid` styling from parent `Field` or group contexts, so you do not need to mirror state on the label itself.
- If you need a hidden label for an input that has a visible icon or placeholder, prefer `aria-label` on the input over a visually-hidden Label — it keeps the markup simpler and avoids stale labels.

## Full Component Source

```tsx
"use client";

export { Label } from "@prototyperco/ui/components/label";
```
</component>

<component name="menu" url="https://prototyper-ui.com/docs/components/menu">
# Menu
> 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() {
  const 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() {
  const 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" },
  ];

  const 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: React.MouseEvent) => 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() {
  const [selected, setSelected] = React.useState<Record<number, boolean>>({
    1: true,
    3: true,
  });

  const 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() {
  const [sidebar, setSidebar] = React.useState(true);
  const [searchbar, setSearchbar] = React.useState(false);
  const [tools, setTools] = React.useState(false);
  const [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() {
  const [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() {
  const 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.

## Full Component Source

```tsx
"use client";

export {
  DropdownMenu,
  DropdownMenuPortal,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuLabel,
  DropdownMenuItem,
  DropdownMenuCheckboxItem,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuSeparator,
  DropdownMenuShortcut,
  DropdownMenuSub,
  DropdownMenuSubTrigger,
  DropdownMenuSubContent,
} from "@prototyperco/ui/components/menu";
```
</component>

<component name="menubar" url="https://prototyper-ui.com/docs/components/menubar">
# Menubar
> A horizontal menu bar with multiple dropdown menus, built on Base UI
URL: https://prototyper-ui.com/docs/components/menubar
Base UI reference: https://base-ui.com/react/components/menubar
```tsx
"use client";

import {
  Menubar,
  MenubarContent,
  MenubarItem,
  MenubarMenu,
  MenubarSeparator,
  MenubarShortcut,
  MenubarSub,
  MenubarSubContent,
  MenubarSubTrigger,
  MenubarTrigger,
} from "@/components/ui/menubar";

export default function MenubarDemo() {
  return (
    <Menubar>
      <MenubarMenu>
        <MenubarTrigger>File</MenubarTrigger>
        <MenubarContent>
          <MenubarItem>
            New Tab <MenubarShortcut>Ctrl+T</MenubarShortcut>
          </MenubarItem>
          <MenubarItem>
            New Window <MenubarShortcut>Ctrl+N</MenubarShortcut>
          </MenubarItem>
          <MenubarSeparator />
          <MenubarSub>
            <MenubarSubTrigger>Share</MenubarSubTrigger>
            <MenubarSubContent>
              <MenubarItem>Email</MenubarItem>
              <MenubarItem>Messages</MenubarItem>
            </MenubarSubContent>
          </MenubarSub>
          <MenubarSeparator />
          <MenubarItem>
            Print <MenubarShortcut>Ctrl+P</MenubarShortcut>
          </MenubarItem>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu>
        <MenubarTrigger>Edit</MenubarTrigger>
        <MenubarContent>
          <MenubarItem>
            Undo <MenubarShortcut>Ctrl+Z</MenubarShortcut>
          </MenubarItem>
          <MenubarItem>
            Redo <MenubarShortcut>Ctrl+Y</MenubarShortcut>
          </MenubarItem>
          <MenubarSeparator />
          <MenubarItem>
            Cut <MenubarShortcut>Ctrl+X</MenubarShortcut>
          </MenubarItem>
          <MenubarItem>
            Copy <MenubarShortcut>Ctrl+C</MenubarShortcut>
          </MenubarItem>
          <MenubarItem>
            Paste <MenubarShortcut>Ctrl+V</MenubarShortcut>
          </MenubarItem>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu>
        <MenubarTrigger>View</MenubarTrigger>
        <MenubarContent>
          <MenubarItem>
            Zoom In <MenubarShortcut>Ctrl++</MenubarShortcut>
          </MenubarItem>
          <MenubarItem>
            Zoom Out <MenubarShortcut>Ctrl+-</MenubarShortcut>
          </MenubarItem>
          <MenubarSeparator />
          <MenubarItem>
            Full Screen <MenubarShortcut>F11</MenubarShortcut>
          </MenubarItem>
        </MenubarContent>
      </MenubarMenu>
    </Menubar>
  );
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/menubar.tsx`
- `components/ui/menu.tsx` (dependency)

## Usage

```tsx
import {
  Menubar,
  MenubarMenu,
  MenubarTrigger,
  MenubarContent,
  MenubarItem,
} from "@/components/ui/menubar";

<Menubar>
  <MenubarMenu>
    <MenubarTrigger>File</MenubarTrigger>
    <MenubarContent>
      <MenubarItem>New File</MenubarItem>
      <MenubarItem>Open</MenubarItem>
      <MenubarItem>Save</MenubarItem>
    </MenubarContent>
  </MenubarMenu>
</Menubar>;
```

## Anatomy

```tsx
<Menubar>
  <MenubarMenu>
    <MenubarTrigger />
    <MenubarContent>
      <MenubarLabel />
      <MenubarSeparator />
      <MenubarGroup>
        <MenubarItem>
          <MenubarShortcut />
        </MenubarItem>
      </MenubarGroup>
      <MenubarCheckboxItem />
      <MenubarRadioGroup>
        <MenubarRadioItem />
      </MenubarRadioGroup>
      <MenubarSub>
        <MenubarSubTrigger />
        <MenubarSubContent>
          <MenubarItem />
        </MenubarSubContent>
      </MenubarSub>
    </MenubarContent>
  </MenubarMenu>
</Menubar>
```

| Sub-component         | `data-slot`             | Purpose                               | Required |
| --------------------- | ----------------------- | ------------------------------------- | -------- |
| `Menubar`             | `menubar`               | Root container, horizontal bar        | Yes      |
| `MenubarMenu`         | `menubar-menu`          | Individual menu within the bar        | Yes      |
| `MenubarTrigger`      | `menubar-trigger`       | Button that opens a menu              | Yes      |
| `MenubarPortal`       | `menubar-portal`        | Renders children into a portal        | No       |
| `MenubarContent`      | `menubar-content`       | The popup panel containing menu items | Yes      |
| `MenubarGroup`        | `menubar-group`         | Groups related menu items             | No       |
| `MenubarLabel`        | `menubar-label`         | Non-interactive label for a group     | No       |
| `MenubarItem`         | `menubar-item`          | Individual actionable menu item       | Yes      |
| `MenubarCheckboxItem` | `menubar-checkbox-item` | Toggleable checkbox menu item         | No       |
| `MenubarRadioGroup`   | `menubar-radio-group`   | Groups radio menu items               | No       |
| `MenubarRadioItem`    | `menubar-radio-item`    | Radio-selectable menu item            | No       |
| `MenubarSeparator`    | `menubar-separator`     | Visual separator between items        | No       |
| `MenubarShortcut`     | `menubar-shortcut`      | Keyboard shortcut hint text           | No       |
| `MenubarSub`          | `menubar-sub`           | Root for a submenu                    | No       |
| `MenubarSubTrigger`   | `menubar-sub-trigger`   | Item that opens a submenu             | No       |
| `MenubarSubContent`   | `menubar-sub-content`   | Popup panel for a submenu             | No       |

## Examples

### Application Menu

```tsx
"use client";

import {
  Menubar,
  MenubarContent,
  MenubarItem,
  MenubarMenu,
  MenubarSeparator,
  MenubarShortcut,
  MenubarSub,
  MenubarSubContent,
  MenubarSubTrigger,
  MenubarTrigger,
} from "@/components/ui/menubar";

export default function MenubarDemo() {
  return (
    <Menubar>
      <MenubarMenu>
        <MenubarTrigger>File</MenubarTrigger>
        <MenubarContent>
          <MenubarItem>
            New Tab <MenubarShortcut>Ctrl+T</MenubarShortcut>
          </MenubarItem>
          <MenubarItem>
            New Window <MenubarShortcut>Ctrl+N</MenubarShortcut>
          </MenubarItem>
          <MenubarSeparator />
          <MenubarSub>
            <MenubarSubTrigger>Share</MenubarSubTrigger>
            <MenubarSubContent>
              <MenubarItem>Email</MenubarItem>
              <MenubarItem>Messages</MenubarItem>
            </MenubarSubContent>
          </MenubarSub>
          <MenubarSeparator />
          <MenubarItem>
            Print <MenubarShortcut>Ctrl+P</MenubarShortcut>
          </MenubarItem>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu>
        <MenubarTrigger>Edit</MenubarTrigger>
        <MenubarContent>
          <MenubarItem>
            Undo <MenubarShortcut>Ctrl+Z</MenubarShortcut>
          </MenubarItem>
          <MenubarItem>
            Redo <MenubarShortcut>Ctrl+Y</MenubarShortcut>
          </MenubarItem>
          <MenubarSeparator />
          <MenubarItem>
            Cut <MenubarShortcut>Ctrl+X</MenubarShortcut>
          </MenubarItem>
          <MenubarItem>
            Copy <MenubarShortcut>Ctrl+C</MenubarShortcut>
          </MenubarItem>
          <MenubarItem>
            Paste <MenubarShortcut>Ctrl+V</MenubarShortcut>
          </MenubarItem>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu>
        <MenubarTrigger>View</MenubarTrigger>
        <MenubarContent>
          <MenubarItem>
            Zoom In <MenubarShortcut>Ctrl++</MenubarShortcut>
          </MenubarItem>
          <MenubarItem>
            Zoom Out <MenubarShortcut>Ctrl+-</MenubarShortcut>
          </MenubarItem>
          <MenubarSeparator />
          <MenubarItem>
            Full Screen <MenubarShortcut>F11</MenubarShortcut>
          </MenubarItem>
        </MenubarContent>
      </MenubarMenu>
    </Menubar>
  );
}
```

## Styling

### Data Slots

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

| Slot name               | Element                      |
| ----------------------- | ---------------------------- |
| `menubar`               | The horizontal bar container |
| `menubar-menu`          | Individual menu root         |
| `menubar-trigger`       | The trigger button           |
| `menubar-portal`        | Portal wrapper               |
| `menubar-content`       | The popup panel              |
| `menubar-group`         | Group wrapper                |
| `menubar-label`         | Group label                  |
| `menubar-item`          | Individual menu item         |
| `menubar-checkbox-item` | Checkbox menu item           |
| `menubar-radio-group`   | Radio group wrapper          |
| `menubar-radio-item`    | Radio menu item              |
| `menubar-separator`     | Visual separator line        |
| `menubar-shortcut`      | Keyboard shortcut text       |
| `menubar-sub`           | Submenu root                 |
| `menubar-sub-trigger`   | Submenu trigger item         |
| `menubar-sub-content`   | Submenu popup panel          |

### Customization Examples

```css
/* Change menubar background */
[data-slot="menubar"] {
  @apply bg-muted;
}

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

```tsx
{
  /* Override styles via className */
}
<Menubar className="rounded-lg">
  <MenubarMenu>
    <MenubarTrigger className="font-bold">File</MenubarTrigger>
    <MenubarContent className="w-64">
      <MenubarItem className="font-medium">Custom Item</MenubarItem>
    </MenubarContent>
  </MenubarMenu>
</Menubar>;
```

## API Reference

### Menubar

Root container that renders a horizontal menu bar.

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

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

### MenubarMenu

Individual menu within the menu bar. Wraps `DropdownMenu`.

| 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`.

### MenubarTrigger

Button within the menu bar that opens a dropdown menu.

| 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`.

### MenubarContent

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` | `-4` | Offset from the alignment edge |
| `sideOffset` | `number` | `8` | 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`.

### MenubarGroup

Groups related menu items together.

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

### MenubarLabel

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`.

### MenubarItem

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`.

### MenubarCheckboxItem

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`.

### MenubarRadioGroup

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`.

### MenubarRadioItem

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`.

### MenubarSeparator

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`.

### MenubarShortcut

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`.

### MenubarSub

Root provider for a submenu.

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

### MenubarSubTrigger

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`.

### MenubarSubContent

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 [Base UI Menu.SubmenuPopup props](https://base-ui.com/react/components/menu) 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 the next menu or a submenu            |
| `ArrowLeft`  | Opens the previous menu or closes a submenu |
| `Escape`     | Closes the currently open menu              |
| `Home`       | Moves focus to the first menu item          |
| `End`        | Moves focus to the last menu item           |

### ARIA Attributes

- `Menubar` receives `role="menubar"`.
- `MenubarTrigger` receives `role="menuitem"` within the menubar context.
- `MenubarContent` receives `role="menu"`.
- `MenubarItem` receives `role="menuitem"`.
- `MenubarCheckboxItem` receives `role="menuitemcheckbox"` with `aria-checked`.
- `MenubarRadioItem` receives `role="menuitemradio"` with `aria-checked`.
- `MenubarSub` content receives `role="menu"` for nested menus.
- `data-disabled` is set on disabled items, which sets `aria-disabled`.
- Focus is managed within the menu bar and returns to the trigger when a menu closes.

## Full Component Source

```tsx
"use client";

export {
  Menubar,
  MenubarPortal,
  MenubarMenu,
  MenubarTrigger,
  MenubarContent,
  MenubarGroup,
  MenubarSeparator,
  MenubarLabel,
  MenubarItem,
  MenubarShortcut,
  MenubarCheckboxItem,
  MenubarRadioGroup,
  MenubarRadioItem,
  MenubarSub,
  MenubarSubTrigger,
  MenubarSubContent,
} from "@prototyperco/ui/components/menubar";
```
</component>

<component name="meter" url="https://prototyper-ui.com/docs/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" \| "info"` | `"default"` | Color variant for the track |
| `size` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` | Track height variant |
| `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", size: "lg" })}>
  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.

## Full Component Source

```tsx
"use client";

export {
  Meter,
  MeterTrack,
  MeterIndicator,
  MeterLabel,
  MeterValue,
  meterIndicatorVariants,
  meterTrackVariants,
} from "@prototyperco/ui/components/meter";
```
</component>

<component name="navigation-menu" url="https://prototyper-ui.com/docs/components/navigation-menu">
# Navigation Menu
> site navigation component with dropdown menus on Base UI
URL: https://prototyper-ui.com/docs/components/navigation-menu
Base UI reference: https://base-ui.com/react/components/navigation-menu
```tsx
"use client";

import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
  navigationMenuTriggerStyle,
} from "@/components/ui/navigation-menu";

export default function NavigationMenuDemo() {
  return (
    <NavigationMenu>
      <NavigationMenuList>
        <NavigationMenuItem>
          <NavigationMenuTrigger>Getting Started</NavigationMenuTrigger>
          <NavigationMenuContent>
            <div className="grid w-[400px] gap-1 md:w-[500px] md:grid-cols-2">
              <NavigationMenuLink href="#">
                <div>
                  <div className="font-medium">Introduction</div>
                  <p className="text-muted-foreground text-xs leading-snug">
                    Learn the basics and get up and running quickly.
                  </p>
                </div>
              </NavigationMenuLink>
              <NavigationMenuLink href="#">
                <div>
                  <div className="font-medium">Installation</div>
                  <p className="text-muted-foreground text-xs leading-snug">
                    Step-by-step guide to install and configure.
                  </p>
                </div>
              </NavigationMenuLink>
              <NavigationMenuLink href="#">
                <div>
                  <div className="font-medium">Typography</div>
                  <p className="text-muted-foreground text-xs leading-snug">
                    Styles for headings, paragraphs, and lists.
                  </p>
                </div>
              </NavigationMenuLink>
              <NavigationMenuLink href="#">
                <div>
                  <div className="font-medium">CLI</div>
                  <p className="text-muted-foreground text-xs leading-snug">
                    Add components using the command line.
                  </p>
                </div>
              </NavigationMenuLink>
            </div>
          </NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuItem>
          <NavigationMenuTrigger>Components</NavigationMenuTrigger>
          <NavigationMenuContent>
            <div className="grid w-[400px] gap-1 md:w-[500px] md:grid-cols-2">
              <NavigationMenuLink href="#">
                <div>
                  <div className="font-medium">Button</div>
                  <p className="text-muted-foreground text-xs leading-snug">
                    Trigger actions and events.
                  </p>
                </div>
              </NavigationMenuLink>
              <NavigationMenuLink href="#">
                <div>
                  <div className="font-medium">Dialog</div>
                  <p className="text-muted-foreground text-xs leading-snug">
                    Modal and non-modal overlays.
                  </p>
                </div>
              </NavigationMenuLink>
              <NavigationMenuLink href="#">
                <div>
                  <div className="font-medium">Select</div>
                  <p className="text-muted-foreground text-xs leading-snug">
                    Pick a value from a dropdown list.
                  </p>
                </div>
              </NavigationMenuLink>
              <NavigationMenuLink href="#">
                <div>
                  <div className="font-medium">Tabs</div>
                  <p className="text-muted-foreground text-xs leading-snug">
                    Organize content into tabbed panels.
                  </p>
                </div>
              </NavigationMenuLink>
            </div>
          </NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuItem>
          <NavigationMenuLink href="#" className={navigationMenuTriggerStyle()}>
            Documentation
          </NavigationMenuLink>
        </NavigationMenuItem>
      </NavigationMenuList>
    </NavigationMenu>
  );
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/navigation-menu.tsx`

## Usage

```tsx
import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
} from "@/components/ui/navigation-menu";

<NavigationMenu>
  <NavigationMenuList>
    <NavigationMenuItem>
      <NavigationMenuTrigger>Item One</NavigationMenuTrigger>
      <NavigationMenuContent>
        <NavigationMenuLink href="/docs">Documentation</NavigationMenuLink>
      </NavigationMenuContent>
    </NavigationMenuItem>
    <NavigationMenuItem>
      <NavigationMenuLink href="/about">About</NavigationMenuLink>
    </NavigationMenuItem>
  </NavigationMenuList>
</NavigationMenu>;
```

## Anatomy

```tsx
<NavigationMenu>
  <NavigationMenuList>
    <NavigationMenuItem>
      <NavigationMenuTrigger />
      <NavigationMenuContent>
        <NavigationMenuLink />
      </NavigationMenuContent>
    </NavigationMenuItem>
  </NavigationMenuList>
</NavigationMenu>
```

| Sub-component              | `data-slot`                  | Purpose                                                        | Required |
| -------------------------- | ---------------------------- | -------------------------------------------------------------- | -------- |
| `NavigationMenu`           | `navigation-menu`            | Root provider, manages open state and renders the positioner   | Yes      |
| `NavigationMenuList`       | `navigation-menu-list`       | Container for menu items                                       | Yes      |
| `NavigationMenuItem`       | `navigation-menu-item`       | Wraps a single trigger + content pair or a standalone link     | Yes      |
| `NavigationMenuTrigger`    | `navigation-menu-trigger`    | Button that opens a dropdown content area                      | No       |
| `NavigationMenuContent`    | `navigation-menu-content`    | Dropdown panel associated with a trigger                       | No       |
| `NavigationMenuLink`       | `navigation-menu-link`       | Link item inside the content or used standalone                | No       |
| `NavigationMenuPositioner` | `navigation-menu-positioner` | Positions the popup relative to the trigger (rendered by root) | Auto     |
| `NavigationMenuIndicator`  | `navigation-menu-indicator`  | Optional visual indicator arrow                                | No       |

## Examples

### With Dropdowns

```tsx
"use client";

import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
  navigationMenuTriggerStyle,
} from "@/components/ui/navigation-menu";

export default function NavigationMenuDemo() {
  return (
    <NavigationMenu>
      <NavigationMenuList>
        <NavigationMenuItem>
          <NavigationMenuTrigger>Getting Started</NavigationMenuTrigger>
          <NavigationMenuContent>
            <div className="grid w-[400px] gap-1 md:w-[500px] md:grid-cols-2">
              <NavigationMenuLink href="#">
                <div>
                  <div className="font-medium">Introduction</div>
                  <p className="text-muted-foreground text-xs leading-snug">
                    Learn the basics and get up and running quickly.
                  </p>
                </div>
              </NavigationMenuLink>
              <NavigationMenuLink href="#">
                <div>
                  <div className="font-medium">Installation</div>
                  <p className="text-muted-foreground text-xs leading-snug">
                    Step-by-step guide to install and configure.
                  </p>
                </div>
              </NavigationMenuLink>
              <NavigationMenuLink href="#">
                <div>
                  <div className="font-medium">Typography</div>
                  <p className="text-muted-foreground text-xs leading-snug">
                    Styles for headings, paragraphs, and lists.
                  </p>
                </div>
              </NavigationMenuLink>
              <NavigationMenuLink href="#">
                <div>
                  <div className="font-medium">CLI</div>
                  <p className="text-muted-foreground text-xs leading-snug">
                    Add components using the command line.
                  </p>
                </div>
              </NavigationMenuLink>
            </div>
          </NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuItem>
          <NavigationMenuTrigger>Components</NavigationMenuTrigger>
          <NavigationMenuContent>
            <div className="grid w-[400px] gap-1 md:w-[500px] md:grid-cols-2">
              <NavigationMenuLink href="#">
                <div>
                  <div className="font-medium">Button</div>
                  <p className="text-muted-foreground text-xs leading-snug">
                    Trigger actions and events.
                  </p>
                </div>
              </NavigationMenuLink>
              <NavigationMenuLink href="#">
                <div>
                  <div className="font-medium">Dialog</div>
                  <p className="text-muted-foreground text-xs leading-snug">
                    Modal and non-modal overlays.
                  </p>
                </div>
              </NavigationMenuLink>
              <NavigationMenuLink href="#">
                <div>
                  <div className="font-medium">Select</div>
                  <p className="text-muted-foreground text-xs leading-snug">
                    Pick a value from a dropdown list.
                  </p>
                </div>
              </NavigationMenuLink>
              <NavigationMenuLink href="#">
                <div>
                  <div className="font-medium">Tabs</div>
                  <p className="text-muted-foreground text-xs leading-snug">
                    Organize content into tabbed panels.
                  </p>
                </div>
              </NavigationMenuLink>
            </div>
          </NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuItem>
          <NavigationMenuLink href="#" className={navigationMenuTriggerStyle()}>
            Documentation
          </NavigationMenuLink>
        </NavigationMenuItem>
      </NavigationMenuList>
    </NavigationMenu>
  );
}
```

## Styling

### Data Slots

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

| Slot name                         | Element                               |
| --------------------------------- | ------------------------------------- |
| `navigation-menu`                 | Root wrapper                          |
| `navigation-menu-list`            | Container for items                   |
| `navigation-menu-item`            | Individual item wrapper               |
| `navigation-menu-trigger`         | Trigger button that opens content     |
| `navigation-menu-content`         | Dropdown content panel                |
| `navigation-menu-link`            | Link inside content or standalone     |
| `navigation-menu-positioner`      | Floating positioner element           |
| `navigation-menu-popup`           | Popup container within the positioner |
| `navigation-menu-viewport`        | Viewport inside the popup             |
| `navigation-menu-indicator`       | Optional indicator arrow              |
| `navigation-menu-indicator-arrow` | Arrow element inside the indicator    |

### Customization Examples

```css
/* Wider dropdown content */
[data-slot="navigation-menu-content"] {
  @apply p-4;
}

/* Custom trigger active state */
[data-slot="navigation-menu-trigger"][data-popup-open] {
  @apply bg-primary text-primary-foreground;
}
```

```tsx
{
  /* Style the navigation menu list with additional gap */
}
<NavigationMenuList className="gap-1">
  <NavigationMenuItem>
    <NavigationMenuTrigger>Item</NavigationMenuTrigger>
    <NavigationMenuContent>...</NavigationMenuContent>
  </NavigationMenuItem>
</NavigationMenuList>;
```

## API Reference

### NavigationMenu

Root component that manages navigation state and renders the popup positioner.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"start" \| "center" \| "end"` | `"start"` | Alignment of the popup relative to the trigger |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Navigation menu content |

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

### NavigationMenuList

Container for navigation menu items.

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

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

### NavigationMenuItem

Wraps a trigger + content pair or a standalone link.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Trigger and content, or a standalone link |

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

### NavigationMenuTrigger

Button that opens the associated dropdown content.

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

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

### NavigationMenuContent

Dropdown panel shown when its associated trigger is activated.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Content items, typically NavigationMenuLink elements |

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

### NavigationMenuLink

A link element inside the navigation menu. Can be used within content dropdowns or as a standalone item.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` | - | URL the link points to |
| `active` | `boolean` | `false` | Whether the link is the currently active page |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Link label content |

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

### NavigationMenuPositioner

Controls the position of the popup. Rendered automatically by `NavigationMenu`; you do not need to add it manually.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | Which side of the trigger to place the popup |
| `sideOffset` | `number` | `8` | Distance from the trigger in pixels |
| `align` | `"start" \| "center" \| "end"` | `"start"` | Alignment of the popup along the trigger edge |
| `alignOffset` | `number` | `0` | Offset along the alignment axis in pixels |
| `className` | `string` | - | Additional CSS classes |

### NavigationMenuIndicator

Optional visual indicator arrow displayed below the active trigger.

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

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

### navigationMenuTriggerStyle

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

```tsx
import { navigationMenuTriggerStyle } from "@/components/ui/navigation-menu";

<NavigationMenuLink href="/docs" className={navigationMenuTriggerStyle()}>
  Documentation
</NavigationMenuLink>;
```

## Accessibility

### Keyboard Interactions

| Key          | Action                                                            |
| ------------ | ----------------------------------------------------------------- |
| `Space`      | Opens the dropdown when a trigger is focused                      |
| `Enter`      | Opens the dropdown when a trigger is focused, activates links     |
| `ArrowDown`  | Opens the dropdown from a trigger; moves focus within content     |
| `ArrowUp`    | Moves focus within content                                        |
| `ArrowRight` | Moves focus to the next trigger in the list                       |
| `ArrowLeft`  | Moves focus to the previous trigger in the list                   |
| `Home`       | Moves focus to the first trigger                                  |
| `End`        | Moves focus to the last trigger                                   |
| `Escape`     | Closes the open dropdown and returns focus to the trigger         |
| `Tab`        | Moves focus out of the navigation menu, closing any open dropdown |

### ARIA Attributes

- The root element renders with `role="navigation"`.
- Each trigger renders with `aria-expanded` and `aria-haspopup` attributes.
- The content panel is linked to its trigger via `aria-controls`.
- Links render with `role="link"`.
- Active links can be marked with `data-active="true"` for `aria-current` behavior.

## Full Component Source

```tsx
"use client";

export {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuIndicator,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
  navigationMenuTriggerStyle,
  NavigationMenuPositioner,
} from "@prototyperco/ui/components/navigation-menu";
```
</component>

<component name="number-field" url="https://prototyper-ui.com/docs/components/number-field">
# NumberField
> A number input with increment/decrement controls built on Base UI
URL: https://prototyper-ui.com/docs/components/number-field
Base UI reference: https://base-ui.com/react/components/number-field
```tsx
import {
  NumberField,
  NumberFieldGroup,
  NumberFieldInput,
  NumberFieldSteppers,
} from "@/components/ui/number-field";
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/number-field.json
```

This will add the following files to your project:

- `components/ui/number-field.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/number-field";

<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/number-field";
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/number-field";
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/number-field";
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/number-field";
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/number-field";
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/number-field";
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/number-field";
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/number-field";
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/number-field";
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/number-field";
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/number-field";
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/number-field";

<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.

## Full Component Source

```tsx
"use client";

export {
  NumberField,
  NumberFieldGroup,
  numberFieldGroupVariants,
  NumberFieldInput,
  NumberFieldIncrement,
  NumberFieldDecrement,
  NumberFieldSteppers,
  NumberFieldScrubArea,
  NumberFieldScrubAreaCursor,
} from "@prototyperco/ui/components/number-field";
```
</component>

<component name="popover" url="https://prototyper-ui.com/docs/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.

## Full Component Source

```tsx
"use client";

export {
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from "@prototyperco/ui/components/popover";
```
</component>

<component name="preview-card" url="https://prototyper-ui.com/docs/components/preview-card">
# Hover Card
> popup showing content preview on link hover
URL: https://prototyper-ui.com/docs/components/preview-card
Base UI reference: https://base-ui.com/react/components/preview-card
```tsx
"use client";

import {
  HoverCard,
  HoverCardContent,
  HoverCardTrigger,
} from "@/components/ui/preview-card";

export default function PreviewCardDemo() {
  return (
    <HoverCard>
      <HoverCardTrigger href="https://base-ui.com">
        <span className="text-sm font-medium underline decoration-foreground/30 underline-offset-4 hover-only:hover:decoration-foreground">
          @base-ui
        </span>
      </HoverCardTrigger>
      <HoverCardContent>
        <div className="flex flex-col gap-2">
          <h4 className="text-sm font-semibold">Base UI</h4>
          <p className="text-sm text-muted-foreground">
            Unstyled React components for building accessible UIs. Created and
            maintained by MUI.
          </p>
          <div className="flex items-center gap-4 pt-1">
            <div className="flex items-center gap-1 text-xs text-muted-foreground">
              <span className="size-2 rounded-full bg-blue-500" />
              TypeScript
            </div>
          </div>
        </div>
      </HoverCardContent>
    </HoverCard>
  );
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/preview-card.tsx`

## Usage

```tsx
import {
  HoverCard,
  HoverCardTrigger,
  HoverCardContent,
} from "@/components/ui/preview-card";

<HoverCard>
  <HoverCardTrigger href="https://example.com">@example</HoverCardTrigger>
  <HoverCardContent>
    <p>Preview content here.</p>
  </HoverCardContent>
</HoverCard>;
```

## Anatomy

```tsx
<HoverCard>
  <HoverCardTrigger />
  <HoverCardContent>{/* your preview content */}</HoverCardContent>
</HoverCard>
```

| Sub-component      | `data-slot`          | Purpose                                   | Required |
| ------------------ | -------------------- | ----------------------------------------- | -------- |
| `HoverCard`        | `hover-card`         | Root provider, manages open/close state   | Yes      |
| `HoverCardTrigger` | `hover-card-trigger` | Link element that shows the card on hover | Yes      |
| `HoverCardContent` | `hover-card-content` | The popup panel anchored to the trigger   | Yes      |

## Styling

### Data Slots

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

| Slot name            | Element                         |
| -------------------- | ------------------------------- |
| `hover-card`         | Root provider (no DOM rendered) |
| `hover-card-trigger` | The trigger link element        |
| `hover-card-portal`  | Portal container                |
| `hover-card-content` | The popup panel                 |

### Customization Examples

```css
/* Make hover card wider */
[data-slot="hover-card-content"] {
  @apply w-80;
}

/* Style the trigger link */
[data-slot="hover-card-trigger"] {
  @apply underline decoration-foreground/30 underline-offset-4;
}
```

```tsx
{
  /* Override styles via className */
}
<HoverCardContent className="w-96 p-6">
  {/* Rich preview content */}
</HoverCardContent>;
```

## API Reference

### HoverCard

Root component that manages open/close state. The card opens when the trigger is hovered.

| 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 PreviewCard.Root props](https://base-ui.com/react/components/preview-card) are forwarded via `...props`.

### HoverCardTrigger

The link element that shows the hover card when hovered. Renders an `<a>` element by default.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` | - | URL the link points to |
| `className` | `string` | - | Additional CSS classes |

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

### HoverCardContent

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` | `4` | 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` | - | Hover card content |

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

## Accessibility

### Keyboard Interactions

| Key      | Action                |
| -------- | --------------------- |
| `Escape` | Closes the hover card |

### ARIA Attributes

- The trigger renders as an `<a>` element, providing native link semantics.
- The hover card is intended for sighted users as a progressive enhancement -- the link remains functional without the card.
- Content inside the card is not announced to screen readers unless focused.
- The card opens on hover with a default delay of 600ms and closes with a 300ms delay.

## Full Component Source

```tsx
"use client";

export {
  HoverCard,
  HoverCardTrigger,
  HoverCardContent,
} from "@prototyperco/ui/components/preview-card";
```
</component>

<component name="progress" url="https://prototyper-ui.com/docs/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 |
| `size` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` | Size variant for the track height |
| `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.

## Compose

This component is available in [`@prototyperco/compose`](/docs/compose).

### Catalog Definition

```typescript title="progress.catalog.ts"
import { z } from "zod";
import { defineComponent } from "@prototyperco/compose/catalog";

export default defineComponent({
  description: "A progress bar indicating completion status",
  props: z.object({
    value: z.number().min(0).max(100).describe("Progress value from 0 to 100"),
    label: z
      .string()
      .optional()
      .describe("Label displayed above the progress bar"),
    color: z
      .enum(["default", "success", "warning", "destructive", "info"])
      .optional()
      .describe("Color variant of the progress fill"),
    size: z
      .enum(["sm", "md", "lg", "xl"])
      .optional()
      .describe("Height of the progress bar"),
  }),
  example: {
    value: 65,
    label: "Upload progress",
    color: "default",
    size: "md",
  },
});
```

### Example Spec

```json
{
  "root": "progress",
  "elements": {
    "progress": {
      "type": "Progress",
      "props": {
        "value": 65,
        "label": "Upload progress",
        "color": "default",
        "size": "md"
      }
    }
  }
}
```

Learn more in the [Compose documentation](/docs/compose).

## Full Component Source

```tsx
"use client";

export {
  Progress,
  ProgressTrack,
  ProgressIndicator,
  ProgressLabel,
  ProgressValue,
  progressIndicatorVariants,
  progressTrackVariants,
} from "@prototyperco/ui/components/progress";
```
</component>

<component name="radio-group" url="https://prototyper-ui.com/docs/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 (internal element managed by `RadioGroupItem`, not composable) | —        |

## 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.

## Compose

This component is available in [`@prototyperco/compose`](/docs/compose).

### Catalog Definition

```typescript title="radio-group.catalog.ts"
import { z } from "zod";
import { defineComponent } from "@prototyperco/compose/catalog";

export default defineComponent({
  description:
    "A group of radio buttons for selecting a single option from a list",
  props: z.object({
    label: z.string().optional().describe("Label for the radio group fieldset"),
    options: z
      .array(
        z.object({
          label: z.string().describe("Display label for the option"),
          value: z.string().describe("Value of the option"),
        }),
      )
      .describe("Available radio options"),
    value: z
      .string()
      .optional()
      .describe("Currently selected value (bindable)"),
    orientation: z
      .enum(["vertical", "horizontal"])
      .optional()
      .describe("Layout direction of the radio buttons"),
    disabled: z
      .boolean()
      .optional()
      .describe("Whether the radio group is disabled"),
  }),
  events: ["change"],
  example: {
    label: "Select a plan",
    options: [
      { label: "Free", value: "free" },
      { label: "Pro", value: "pro" },
      { label: "Enterprise", value: "enterprise" },
    ],
    value: "free",
  },
});
```

### Example Spec

```json
{
  "root": "planPicker",
  "elements": {
    "planPicker": {
      "type": "RadioGroup",
      "props": {
        "label": "Select a plan",
        "options": [
          { "label": "Free", "value": "free" },
          { "label": "Pro", "value": "pro" },
          { "label": "Enterprise", "value": "enterprise" }
        ],
        "value": "free"
      },
      "$bindState": { "path": "/selectedPlan", "event": "change" }
    }
  }
}
```

Learn more in the [Compose documentation](/docs/compose).

## Full Component Source

```tsx
"use client";

export {
  RadioGroup,
  RadioGroupItem,
} from "@prototyperco/ui/components/radio-group";
```
</component>

<component name="resizable-panel" url="https://prototyper-ui.com/docs/components/resizable-panel">
# Resizable Panel
> Resizable split panels with drag handles for flexible layouts
URL: https://prototyper-ui.com/docs/components/resizable-panel
```tsx
import {
  ResizablePanelGroup,
  ResizablePanel,
  ResizableHandle,
} from "@/components/ui/resizable-panel";

export default function ResizablePanelDemo() {
  return (
    <ResizablePanelGroup
      orientation="horizontal"
      className="min-h-[200px] max-w-md rounded-lg border border-border"
    >
      <ResizablePanel defaultSize="50%" minSize="20%">
        <div className="flex h-full items-center justify-center p-6">
          <span className="font-semibold text-sm text-muted-foreground">
            Panel A
          </span>
        </div>
      </ResizablePanel>
      <ResizableHandle withHandle />
      <ResizablePanel defaultSize="50%" minSize="20%">
        <div className="flex h-full items-center justify-center p-6">
          <span className="font-semibold text-sm text-muted-foreground">
            Panel B
          </span>
        </div>
      </ResizablePanel>
    </ResizablePanelGroup>
  );
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/resizable-panel.tsx`

### Dependencies

This component uses [`react-resizable-panels`](https://github.com/bvaughn/react-resizable-panels) under the hood. It will be installed automatically.

## Usage

```tsx
import {
  ResizablePanelGroup,
  ResizablePanel,
  ResizableHandle,
} from "@/components/ui/resizable-panel";

<ResizablePanelGroup orientation="horizontal">
  <ResizablePanel defaultSize="50%">Left panel content</ResizablePanel>
  <ResizableHandle withHandle />
  <ResizablePanel defaultSize="50%">Right panel content</ResizablePanel>
</ResizablePanelGroup>;
```

## Anatomy

```tsx
<ResizablePanelGroup>
  <ResizablePanel />
  <ResizableHandle />
  <ResizablePanel />
</ResizablePanelGroup>
```

| Sub-component         | `data-slot`             | Purpose                              | Required |
| --------------------- | ----------------------- | ------------------------------------ | -------- |
| `ResizablePanelGroup` | `resizable-panel-group` | Container that manages panel layout  | Yes      |
| `ResizablePanel`      | `resizable-panel`       | Individual panel with resizable size | Yes      |
| `ResizableHandle`     | `resizable-handle`      | Drag handle between panels           | Yes      |

## Examples

### Vertical orientation

```tsx
<ResizablePanelGroup orientation="vertical" className="min-h-[300px]">
  <ResizablePanel defaultSize="60%">Top</ResizablePanel>
  <ResizableHandle />
  <ResizablePanel defaultSize="40%">Bottom</ResizablePanel>
</ResizablePanelGroup>
```

### Three panels

```tsx
<ResizablePanelGroup orientation="horizontal">
  <ResizablePanel defaultSize="25%" minSize="15%">
    Sidebar
  </ResizablePanel>
  <ResizableHandle withHandle />
  <ResizablePanel defaultSize="50%">Main</ResizablePanel>
  <ResizableHandle withHandle />
  <ResizablePanel defaultSize="25%" minSize="15%">
    Inspector
  </ResizablePanel>
</ResizablePanelGroup>
```

## Styling

### Data Slots

| Slot name               | Element                       |
| ----------------------- | ----------------------------- |
| `resizable-panel-group` | Flex container for all panels |
| `resizable-panel`       | Individual panel              |
| `resizable-handle`      | Drag handle separator         |

### Customization Examples

```css
/* Custom handle color */
[data-slot="resizable-handle"] {
  @apply bg-primary/20;
}

/* Wider drag zone */
[data-slot="resizable-handle"]::after {
  left: -4px;
  right: -4px;
}
```

## API Reference

### ResizablePanelGroup

Container that manages layout of child panels. Wraps `react-resizable-panels` `Group`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Panel layout direction |
| `className` | `string` | - | Additional CSS classes |

All [`react-resizable-panels` Group props](https://github.com/bvaughn/react-resizable-panels) are forwarded.

### ResizablePanel

Individual resizable panel. Wraps `react-resizable-panels` `Panel`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultSize` | `string` | - | Initial size as percentage (e.g. "50%") |
| `minSize` | `string` | - | Minimum size as percentage |
| `maxSize` | `string` | - | Maximum size as percentage |
| `className` | `string` | - | Additional CSS classes |

All [`react-resizable-panels` Panel props](https://github.com/bvaughn/react-resizable-panels) are forwarded.

### ResizableHandle

Drag handle between panels. Wraps `react-resizable-panels` `Separator`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `withHandle` | `boolean` | `false` | Show a visual grip icon on the handle |
| `className` | `string` | - | Additional CSS classes |

All [`react-resizable-panels` Separator props](https://github.com/bvaughn/react-resizable-panels) are forwarded.

## Accessibility

### Keyboard Interactions

| Key          | Action                                      |
| ------------ | ------------------------------------------- |
| `ArrowLeft`  | Shrinks the panel to the left of the handle |
| `ArrowRight` | Grows the panel to the left of the handle   |
| `ArrowUp`    | Shrinks the panel above the handle          |
| `ArrowDown`  | Grows the panel above the handle            |
| `Home`       | Collapses the panel to its minimum size     |
| `End`        | Expands the panel to its maximum size       |

Keyboard interactions are provided by the underlying `react-resizable-panels` library.

## Full Component Source

```tsx
"use client";

export {
  ResizablePanelGroup,
  ResizablePanel,
  ResizableHandle,
} from "@prototyperco/ui/components/resizable-panel";
```
</component>

<component name="row" url="https://prototyper-ui.com/docs/components/row">
# Row
> A horizontal flex layout with gap, alignment, and justify options.
URL: https://prototyper-ui.com/docs/components/row
```tsx
import { Row } from "@/components/ui/row";

export default function RowDemo() {
  return (
    <Row gap={3} align="center">
      <div className="rounded-lg bg-primary px-4 py-2 text-sm text-primary-foreground">
        Item 1
      </div>
      <div className="rounded-lg bg-primary px-4 py-2 text-sm text-primary-foreground">
        Item 2
      </div>
      <div className="rounded-lg bg-primary px-4 py-2 text-sm text-primary-foreground">
        Item 3
      </div>
    </Row>
  );
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/row.tsx`

## Usage

```tsx
import { Row } from "@/components/ui/row";
```

```tsx
<Row gap={4} align="center" justify="between">
  <span>Left</span>
  <span>Right</span>
</Row>
```

Row is a horizontal flex container with props for `gap`, `align`, `justify`, and `wrap`. Use it for toolbars, header layouts, button groups, and tag lists.

## Examples

### Space Between

A common header pattern with logo on the left and navigation on the right.

```tsx
import { Row } from "@/components/ui/row";

export default function RowBetween() {
  return (
    <Row justify="between" align="center" className="w-full">
      <span className="text-sm font-semibold">Logo</span>
      <Row gap={4}>
        <span className="text-sm text-muted-foreground">Docs</span>
        <span className="text-sm text-muted-foreground">Pricing</span>
        <span className="text-sm text-muted-foreground">Blog</span>
      </Row>
    </Row>
  );
}
```

### Centered

Centered button group, useful for dialog footers and form actions.

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

export default function RowCentered() {
  return (
    <Row justify="center" gap={3}>
      <Button variant="outline" size="sm">
        Cancel
      </Button>
      <Button size="sm">Save Changes</Button>
    </Row>
  );
}
```

### Wrapping

Wrapping row for tags, badges, or chips that overflow to the next line.

```tsx
import { Row } from "@/components/ui/row";
import { Badge } from "@/components/ui/badge";

export default function RowWrap() {
  return (
    <Row gap={2} wrap>
      <Badge>React</Badge>
      <Badge>TypeScript</Badge>
      <Badge>Tailwind CSS</Badge>
      <Badge>Base UI</Badge>
      <Badge>Next.js</Badge>
      <Badge>Turborepo</Badge>
      <Badge>pnpm</Badge>
      <Badge>Vitest</Badge>
    </Row>
  );
}
```

## Styling

### Data Slots

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

| Slot name | Element          |
| --------- | ---------------- |
| `row`     | The `<div>` root |

### Customization Examples

```css
/* Add a bottom border to all rows */
[data-slot="row"] {
  @apply border-b border-border pb-2;
}
```

```tsx
<Row className="border-b border-border pb-2" gap={4}>
  Custom styled row
</Row>
```

## API Reference

### Row

A horizontal flex container with layout props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `gap` | `number` | `3` | Gap between items. Maps to Tailwind gap utilities (0, 1, 2, 3, 4, 5, 6, 8, 10, 12). |
| `align` | `"start" \| "center" \| "end" \| "stretch" \| "baseline"` | `"center"` | Vertical alignment of items (items-*). |
| `justify` | `"start" \| "center" \| "end" \| "between" \| "around" \| "evenly"` | `"start"` | Horizontal distribution of items (justify-*). |
| `wrap` | `boolean` | `false` | Whether items wrap to the next line when they overflow. |
| `className` | `string` | - | Additional CSS classes. |
| `children` | `React.ReactNode` | - | Row content. |

Extends `React.ComponentProps<"div">`. All standard div props are forwarded via `...props`.

## Accessibility

### Keyboard Interactions

Row is a non-interactive layout container and does not have keyboard interactions.

### ARIA Attributes

- Renders as a plain `<div>` with no implicit ARIA role.
- No additional ARIA attributes are needed for a flex layout container.

## Full Component Source

```tsx
"use client";

export { Row } from "@prototyperco/ui/components/row";
```
</component>

<component name="scroll-area" url="https://prototyper-ui.com/docs/components/scroll-area">
# Scroll Area
> A scrollable container with custom styled scrollbars
URL: https://prototyper-ui.com/docs/components/scroll-area
Base UI reference: https://base-ui.com/react/components/scroll-area
```tsx
"use client";

import { ScrollArea } from "@/components/ui/scroll-area";

const tags = Array.from({ length: 50 }).map(
  (_, i, a) => `v1.2.0-beta.${a.length - i}`,
);

export default function ScrollAreaDemo() {
  return (
    <ScrollArea className="h-72 w-48 rounded-md border">
      <div className="p-4">
        <h4 className="mb-4 text-sm font-medium leading-none">Tags</h4>
        {tags.map((tag) => (
          <div key={tag} className="text-sm">
            {tag}
            <div className="my-2 h-px shrink-0 bg-border" />
          </div>
        ))}
      </div>
    </ScrollArea>
  );
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/scroll-area.tsx`

## Usage

```tsx
import { ScrollArea } from "@/components/ui/scroll-area";

<ScrollArea className="h-72 w-48 rounded-md border">
  <div className="p-4">{/* Long content here */}</div>
</ScrollArea>;
```

## Anatomy

```tsx
<ScrollArea>
  {/* ScrollArea.Viewport, ScrollBar, and ScrollArea.Corner are rendered internally */}
  <div>Your scrollable content</div>
</ScrollArea>
```

| Sub-component | `data-slot`             | Purpose                                         | Required |
| ------------- | ----------------------- | ----------------------------------------------- | -------- |
| `ScrollArea`  | `scroll-area`           | Root container with built-in viewport/scrollbar | Yes      |
| `ScrollBar`   | `scroll-area-scrollbar` | Scrollbar track (vertical or horizontal)        | Internal |
| Viewport      | `scroll-area-viewport`  | Scrollable viewport container                   | Internal |
| Thumb         | `scroll-area-thumb`     | Draggable scrollbar indicator                   | Internal |

> **Note:** The viewport, scrollbar, thumb, and corner are rendered automatically inside the `ScrollArea` component. You only need to provide child content.

## Styling

### Data Slots

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

| Slot name               | Element                   |
| ----------------------- | ------------------------- |
| `scroll-area`           | Root wrapper              |
| `scroll-area-viewport`  | Scrollable viewport       |
| `scroll-area-scrollbar` | Scrollbar track           |
| `scroll-area-thumb`     | Scrollbar thumb indicator |

### Customization Examples

```css
/* Make the scrollbar wider */
[data-slot="scroll-area-scrollbar"] {
  @apply w-3.5;
}

/* Custom thumb color */
[data-slot="scroll-area-thumb"] {
  @apply bg-primary/50;
}
```

```tsx
{
  /* Add horizontal scrollbar with the ScrollBar component */
}
import { ScrollArea, ScrollBar } from "@/components/ui/scroll-area";

<ScrollArea className="w-96 whitespace-nowrap rounded-md border">
  <div className="flex w-max space-x-4 p-4">
    {items.map((item) => (
      <div key={item} className="w-40 shrink-0">
        {item}
      </div>
    ))}
  </div>
  <ScrollBar orientation="horizontal" />
</ScrollArea>;
```

## API Reference

### ScrollArea

Root component that provides a scrollable viewport with custom scrollbars. Renders a vertical scrollbar by default.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes for the root container |
| `children` | `React.ReactNode` | - | Scrollable content |

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

### ScrollBar

A scrollbar track with a draggable thumb. One vertical scrollbar is rendered by default inside `ScrollArea`. Use this component to add an additional horizontal scrollbar.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | The axis the scrollbar controls |
| `className` | `string` | - | Additional CSS classes for the scrollbar |

All [Base UI ScrollArea.Scrollbar props](https://base-ui.com/react/components/scroll-area) are forwarded via `...props`.

## Accessibility

### Keyboard Interactions

| Key                        | Description                                           |
| -------------------------- | ----------------------------------------------------- |
| `Tab`                      | Moves focus into the scroll area viewport             |
| `ArrowUp` / `ArrowDown`    | Scrolls content vertically when viewport is focused   |
| `ArrowLeft` / `ArrowRight` | Scrolls content horizontally when viewport is focused |
| `PageUp` / `PageDown`      | Scrolls content by one page                           |
| `Home` / `End`             | Scrolls to the start or end of content                |

### ARIA Attributes

- The viewport is focusable with `tabindex="0"` and includes a `focus-visible` ring for keyboard users.
- Scroll position is managed natively by the browser, providing standard scrolling behavior and screen reader compatibility.
- The custom scrollbars are decorative overlays; actual scrolling relies on native browser scroll mechanics.
- `data-has-overflow-x` and `data-has-overflow-y` attributes on the root indicate when content exceeds the viewport.
- `data-scrolling` is present on the root during active scrolling.

## Full Component Source

```tsx
"use client";

export { ScrollArea, ScrollBar } from "@prototyperco/ui/components/scroll-area";
```
</component>

<component name="section" url="https://prototyper-ui.com/docs/components/section">
# Section
> A full-width page section with background variants and constrained content.
URL: https://prototyper-ui.com/docs/components/section
```tsx
import { Section } from "@/components/ui/section";

export default function SectionDemo() {
  return (
    <>
      <Section background="none" padding="lg">
        <h2 className="text-2xl font-bold">Hero Section</h2>
        <p className="text-muted-foreground">
          Default background, large padding
        </p>
      </Section>
      <Section background="surface" padding="md">
        <h2 className="text-2xl font-bold">Features</h2>
        <p className="text-muted-foreground">
          Surface background, medium padding
        </p>
      </Section>
      <Section background="muted" padding="lg">
        <h2 className="text-2xl font-bold">Call to Action</h2>
        <p className="text-muted-foreground">Muted background, large padding</p>
      </Section>
    </>
  );
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/section.tsx`

## Usage

```tsx
import { Section } from "@/components/ui/section";
```

```tsx
<Section background="surface" padding="lg">
  <h2>Section heading</h2>
  <p>Section content is automatically constrained and centered.</p>
</Section>
```

Section wraps content in a full-bleed container with an optional background color. The inner content is automatically constrained to a `maxWidth` and centered with horizontal padding.

## Examples

### Primary Background

```tsx
import { Section } from "@/components/ui/section";

export default function SectionPrimary() {
  return (
    <Section background="primary" padding="xl">
      <h2 className="text-2xl font-bold">Get Started Today</h2>
      <p className="text-primary-foreground/80">
        Primary background section for high-impact call-to-action areas.
      </p>
    </Section>
  );
}
```

### Narrow Content

```tsx
import { Section } from "@/components/ui/section";

export default function SectionNarrow() {
  return (
    <Section background="surface" padding="lg" maxWidth="2xl">
      <h2 className="text-2xl font-bold">Focused Content</h2>
      <p className="text-muted-foreground">
        A narrower max-width keeps text readable for long-form content like
        articles and blog posts.
      </p>
    </Section>
  );
}
```

## Styling

### Data Slots

Use `data-slot` attributes to target Section parts in CSS:

| Slot name         | Element                       |
| ----------------- | ----------------------------- |
| `section`         | The outer `<section>` root    |
| `section-content` | The inner constrained `<div>` |

### Customization Examples

```css
/* Add a top border to surface sections */
[data-slot="section"] {
  @apply border-t border-border;
}

/* Override inner content max-width */
[data-slot="section-content"] {
  @apply max-w-3xl;
}
```

```tsx
<Section className="border-t border-border" background="muted" padding="lg">
  Custom styled section
</Section>
```

## API Reference

### Section

A full-bleed section with constrained inner content.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `background` | `"none" \| "default" \| "surface" \| "surface-secondary" \| "surface-tertiary" \| "muted" \| "primary"` | `"none"` | Background color variant for the section. |
| `padding` | `"none" \| "sm" \| "md" \| "lg" \| "xl"` | `"lg"` | Vertical padding applied to the section. |
| `maxWidth` | `"sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "4xl" \| "5xl" \| "full"` | `"5xl"` | Max-width constraint for the inner content. |
| `centered` | `boolean` | `true` | Whether to center the inner content with mx-auto. |
| `className` | `string` | - | Additional CSS classes applied to the outer section. |
| `children` | `React.ReactNode` | - | Section content. |

Extends `React.ComponentProps<"section">`. All standard section props are forwarded via `...props`.

### sectionVariants

A `cva` helper exported for use outside of the `<Section>` component.

```tsx
import { sectionVariants } from "@/components/ui/section";

<div className={sectionVariants({ background: "muted", padding: "lg" })}>
  Custom element with section styles
</div>;
```

## Accessibility

### Keyboard Interactions

Section is a non-interactive presentational container and does not have keyboard interactions.

### ARIA Attributes

- Renders as a native `<section>` element, which is treated as a landmark by assistive technology when given an accessible name.
- Add `aria-label` or `aria-labelledby` to give the section a meaningful label for screen readers.

## Full Component Source

```tsx
"use client";

export { Section, sectionVariants } from "@prototyperco/ui/components/section";
```
</component>

<component name="segmented-control" url="https://prototyper-ui.com/docs/components/segmented-control">
# Segmented Control
> a segmented control for switching between options built on Base UI
URL: https://prototyper-ui.com/docs/components/segmented-control
Base UI reference: https://base-ui.com/react/components/radio-group
```tsx
import {
  SegmentedControl,
  SegmentedControlItem,
} from "@/components/ui/segmented-control";

export default function SegmentedControlDemo() {
  return (
    <SegmentedControl defaultValue="weekly">
      <SegmentedControlItem value="daily">Daily</SegmentedControlItem>
      <SegmentedControlItem value="weekly">Weekly</SegmentedControlItem>
      <SegmentedControlItem value="monthly">Monthly</SegmentedControlItem>
    </SegmentedControl>
  );
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/segmented-control.tsx`

## Usage

```tsx
import {
  SegmentedControl,
  SegmentedControlItem,
} from "@/components/ui/segmented-control";
```

```tsx
<SegmentedControl defaultValue="option-1">
  <SegmentedControlItem value="option-1">Option 1</SegmentedControlItem>
  <SegmentedControlItem value="option-2">Option 2</SegmentedControlItem>
  <SegmentedControlItem value="option-3">Option 3</SegmentedControlItem>
</SegmentedControl>
```

## Anatomy

```tsx
<SegmentedControl>
  <SegmentedControlItem />
</SegmentedControl>
```

| Sub-component          | `data-slot`              | Purpose                        | Required |
| ---------------------- | ------------------------ | ------------------------------ | -------- |
| `SegmentedControl`     | `segmented-control`      | Root container and radio group | Yes      |
| `SegmentedControlItem` | `segmented-control-item` | Individual selectable option   | Yes      |

## Examples

### Small

```tsx
import {
  SegmentedControl,
  SegmentedControlItem,
} from "@/components/ui/segmented-control";

export default function SegmentedControlSmall() {
  return (
    <SegmentedControl defaultValue="list" size="sm">
      <SegmentedControlItem value="grid">Grid</SegmentedControlItem>
      <SegmentedControlItem value="list">List</SegmentedControlItem>
      <SegmentedControlItem value="table">Table</SegmentedControlItem>
    </SegmentedControl>
  );
}
```

## Styling

### Data Slots

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

| Slot name                     | Element                          |
| ----------------------------- | -------------------------------- |
| `segmented-control`           | Root container                   |
| `segmented-control-item`      | Individual option button         |
| `segmented-control-indicator` | Check indicator inside each item |

### Customization Examples

```css
/* Squared segmented control */
[data-slot="segmented-control"] {
  @apply rounded-lg;
}

[data-slot="segmented-control-item"] {
  @apply rounded-md;
}
```

```tsx
<SegmentedControl className="rounded-lg">
  <SegmentedControlItem className="rounded-md" value="a">
    A
  </SegmentedControlItem>
  <SegmentedControlItem className="rounded-md" value="b">
    B
  </SegmentedControlItem>
</SegmentedControl>
```

## API Reference

### SegmentedControl

Root container that manages selection state. Built on Base UI RadioGroup.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "md"` | `"md"` | Size of the segmented control. |
| `value` | `string` | - | Controlled selected value. |
| `defaultValue` | `string` | - | Initial selected value for uncontrolled usage. |
| `onValueChange` | `(value: string, event: Event) => void` | - | Callback when the selected value changes. |
| `disabled` | `boolean` | `false` | Whether the entire control is disabled. |
| `className` | `string` | - | Additional CSS classes. |
| `children` | `React.ReactNode` | - | SegmentedControlItem elements. |

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

### SegmentedControlItem

An individual selectable option within the segmented control.

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

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

### segmentedControlVariants

A `cva` helper exported for applying segmented control styles outside the component.

```tsx
import { segmentedControlVariants } from "@/components/ui/segmented-control";

<div className={segmentedControlVariants({ size: "sm" })}>Custom element</div>;
```

## Accessibility

### Keyboard Interactions

| Key          | Action                                         |
| ------------ | ---------------------------------------------- |
| `Tab`        | Moves focus to the segmented control           |
| `ArrowRight` | Moves focus and selection to the next item     |
| `ArrowLeft`  | Moves focus and selection to the previous item |
| `Space`      | Selects the focused item                       |

### ARIA Attributes

- The root renders with `role="radiogroup"` via Base UI.
- Each item renders with `role="radio"`.
- `aria-checked` is set to `true` on the selected item, `false` on others.
- `aria-disabled` is set when the control or individual items are disabled.

## Full Component Source

```tsx
"use client";

export {
  SegmentedControl,
  SegmentedControlItem,
  segmentedControlVariants,
} from "@prototyperco/ui/components/segmented-control";
```
</component>

<component name="select" url="https://prototyper-ui.com/docs/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.

## Compose

This component is available in [`@prototyperco/compose`](/docs/compose).

### Catalog Definition

```typescript title="select.catalog.ts"
import { z } from "zod";
import { defineComponent } from "@prototyperco/compose/catalog";

export default defineComponent({
  description: "A dropdown select field for choosing from a list of options",
  props: z.object({
    label: z.string().optional().describe("Label displayed above the select"),
    placeholder: z
      .string()
      .optional()
      .describe("Placeholder text when no value is selected"),
    options: z
      .array(
        z.object({
          label: z.string().describe("Display text for the option"),
          value: z.string().describe("Value of the option"),
        }),
      )
      .describe("List of selectable options"),
    value: z.string().optional().describe("Currently selected value"),
    disabled: z.boolean().optional().describe("Whether the select is disabled"),
  }),
  events: ["change"],
  example: {
    label: "Country",
    placeholder: "Select a country...",
    options: [
      { label: "United States", value: "us" },
      { label: "Canada", value: "ca" },
      { label: "United Kingdom", value: "uk" },
    ],
  },
});
```

### Example Spec

```json
{
  "root": "countrySelect",
  "elements": {
    "countrySelect": {
      "type": "Select",
      "props": {
        "label": "Country",
        "placeholder": "Select a country...",
        "options": [
          { "label": "United States", "value": "us" },
          { "label": "Canada", "value": "ca" },
          { "label": "United Kingdom", "value": "uk" }
        ]
      },
      "$bindState": { "path": "/country", "event": "change" }
    }
  }
}
```

Learn more in the [Compose documentation](/docs/compose).

## Full Component Source

```tsx
"use client";

export {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectLabel,
  SelectScrollDownButton,
  SelectScrollUpButton,
  SelectSeparator,
  SelectTrigger,
  selectTriggerVariants,
  SelectValue,
} from "@prototyperco/ui/components/select";
```
</component>

<component name="separator" url="https://prototyper-ui.com/docs/components/separator">
# Separator
> a horizontal or vertical divider built on Base UI
URL: https://prototyper-ui.com/docs/components/separator
Base UI reference: https://base-ui.com/react/components/separator
```tsx
import { Separator } from "@/components/ui/separator";

export default function SeparatorDemo() {
  return (
    <div className="w-full max-w-sm">
      <div className="space-y-1">
        <h4 className="text-sm font-medium leading-none">Prototyper UI</h4>
        <p className="text-muted-foreground text-sm">
          An open-source component library.
        </p>
      </div>
      <Separator className="my-4" />
      <div className="flex h-5 items-center gap-4 text-sm">
        <span>Docs</span>
        <Separator orientation="vertical" />
        <span>Source</span>
        <Separator orientation="vertical" />
        <span>Themes</span>
      </div>
    </div>
  );
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/separator.tsx`

## Usage

```tsx
import { Separator } from "@/components/ui/separator";
```

```tsx
<Separator />
```

## Styling

### Data Slots

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

| Slot name   | Element                    |
| ----------- | -------------------------- |
| `separator` | The separator `<div>` root |

### Customization Examples

```css
/* Custom separator color */
[data-slot="separator"] {
  @apply bg-primary/20;
}

/* Thicker horizontal separator */
[data-slot="separator"][data-horizontal] {
  @apply h-0.5;
}
```

```tsx
<Separator className="bg-primary/20" />
```

## API Reference

### Separator

A visual divider between content sections.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | The orientation of the separator. |
| `className` | `string` | - | Additional CSS classes. |

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

## Accessibility

### Keyboard Interactions

Separator is a non-interactive display element and does not have keyboard interactions.

### ARIA Attributes

- Renders with `role="separator"` via Base UI.
- `aria-orientation` is set to `"horizontal"` or `"vertical"` based on the `orientation` prop.

## Compose

This component is available in [`@prototyperco/compose`](/docs/compose).

### Catalog Definition

```typescript title="separator.catalog.ts"
import { z } from "zod";
import { defineComponent } from "@prototyperco/compose/catalog";

export default defineComponent({
  description: "A visual divider between sections of content",
  props: z.object({
    orientation: z
      .enum(["horizontal", "vertical"])
      .optional()
      .describe("Direction of the separator line, defaults to horizontal"),
    decorative: z
      .boolean()
      .optional()
      .describe(
        "If true, the separator is purely decorative and hidden from assistive technology",
      ),
  }),
  events: [],
  example: { orientation: "horizontal" },
});
```

### Example Spec

```json
{
  "root": "sep",
  "elements": {
    "sep": {
      "type": "Separator",
      "props": {
        "orientation": "horizontal"
      }
    }
  }
}
```

Learn more in the [Compose documentation](/docs/compose).

## Full Component Source

```tsx
"use client";

export { Separator } from "@prototyperco/ui/components/separator";
```
</component>

<component name="skeleton" url="https://prototyper-ui.com/docs/components/skeleton">
# Skeleton
> An animated pulse placeholder for loading states
URL: https://prototyper-ui.com/docs/components/skeleton
Skeletons stand in for content while it's still loading. They preserve the layout of the real UI so the page doesn't jump when data arrives, and the soft pulse animation signals that something is happening without demanding attention. Use skeletons in place of spinners when you can predict the rough shape of the incoming content — a card, a row, an avatar — because matching the final layout reduces perceived wait time more than a generic loader.

```tsx
import { Skeleton } from "@/components/ui/skeleton";

export default function SkeletonDemo() {
  return (
    <div className="flex items-center space-x-4">
      <Skeleton className="size-12 rounded-full" />
      <div className="space-y-2">
        <Skeleton className="h-4 w-[250px]" />
        <Skeleton className="h-4 w-[200px]" />
      </div>
    </div>
  );
}
```

### When to use

- The shape of the data is known ahead of time (lists, cards, profile headers, table rows).
- The wait is long enough to be noticed (roughly 300ms or more) but short enough that a full-page state would be overkill.
- You want to avoid layout shift when content swaps in.

Prefer a spinner or progress indicator when the loading duration is unpredictable, when the layout cannot be approximated, or when the user has just triggered an explicit action like a form submission.

## Installation

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

This will add the following files to your project:

- `components/ui/skeleton.tsx`

## Usage

```tsx
import { Skeleton } from "@/components/ui/skeleton";

<Skeleton className="h-4 w-[200px]" />;
```

## Examples

### Card

```tsx
import { Skeleton } from "@/components/ui/skeleton";

export default function SkeletonCard() {
  return (
    <div className="flex flex-col space-y-3">
      <Skeleton className="h-[125px] w-[250px] rounded-xl" />
      <div className="space-y-2">
        <Skeleton className="h-4 w-[250px]" />
        <Skeleton className="h-4 w-[200px]" />
      </div>
    </div>
  );
}
```

## Styling

### Data Slots

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

| Slot name  | Element          |
| ---------- | ---------------- |
| `skeleton` | The `<div>` root |

### Customization Examples

```css
/* Change animation to a shimmer */
[data-slot="skeleton"] {
  @apply animate-shimmer;
}
```

```tsx
{
  /* Size and shape via className */
}
<Skeleton className="size-12 rounded-full" />;
```

## API Reference

### Skeleton

An animated loading placeholder.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Controls dimensions and shape. Use Tailwind utilities like h-4 w-[200px] rounded-full. |
| `children` | `React.ReactNode` | - | Optional content (typically empty). |

Extends `React.ComponentProps<"div">`. All standard div props are forwarded via `...props`.

## Accessibility

### Keyboard Interactions

Skeleton is a non-interactive presentational element and does not have keyboard interactions.

### ARIA Attributes

- Skeleton renders as a plain `<div>` with no implicit ARIA role.
- For screen readers, set `aria-busy="true"` on the parent container while loading and remove it when content arrives.
- If the skeleton represents content that will be announced (such as a status message), pair it with `aria-live="polite"` on the same container so assistive tech picks up the final value once it swaps in.
- Respect `prefers-reduced-motion`: the default pulse animation is subtle, but you can disable it entirely by overriding the animation utility for users who opt out.

## Full Component Source

```tsx
"use client";

export { Skeleton } from "@prototyperco/ui/components/skeleton";
```
</component>

<component name="slider" url="https://prototyper-ui.com/docs/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.

## Compose

This component is available in [`@prototyperco/compose`](/docs/compose).

### Catalog Definition

```typescript title="slider.catalog.ts"
import { z } from "zod";
import { defineComponent } from "@prototyperco/compose/catalog";

export default defineComponent({
  description:
    "A range slider input for selecting a numeric value within a range",
  props: z.object({
    label: z.string().optional().describe("Label displayed above the slider"),
    min: z.number().optional().describe("Minimum value"),
    max: z.number().optional().describe("Maximum value"),
    step: z.number().optional().describe("Step increment"),
    value: z.number().optional().describe("Current slider value (bindable)"),
    disabled: z.boolean().optional().describe("Whether the slider is disabled"),
  }),
  events: ["change"],
  example: { label: "Volume", min: 0, max: 100, step: 1, value: 50 },
});
```

### Example Spec

```json
{
  "root": "volumeSlider",
  "elements": {
    "volumeSlider": {
      "type": "Slider",
      "props": {
        "label": "Volume",
        "min": 0,
        "max": 100,
        "step": 1,
        "value": 50
      },
      "$bindState": { "path": "/volume", "event": "change" }
    }
  }
}
```

Learn more in the [Compose documentation](/docs/compose).

## Full Component Source

```tsx
"use client";

export {
  Slider,
  SliderControl,
  SliderTrack,
  SliderIndicator,
  SliderThumb,
  SliderOutput,
} from "@prototyperco/ui/components/slider";
```
</component>

<component name="spinner" url="https://prototyper-ui.com/docs/components/spinner">
# Spinner
> An SVG loading spinner with size variants
URL: https://prototyper-ui.com/docs/components/spinner
```tsx
import { Spinner } from "@/components/ui/spinner";

export default function SpinnerDemo() {
  return <Spinner />;
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/spinner.tsx`

## Usage

```tsx
import { Spinner } from "@/components/ui/spinner";

<Spinner />;
```

## Examples

### Sizes

```tsx
import { Spinner } from "@/components/ui/spinner";

export default function SpinnerSizes() {
  return (
    <div className="flex items-center gap-4">
      <Spinner size="sm" />
      <Spinner size="md" />
      <Spinner size="lg" />
    </div>
  );
}
```

### In Button

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

export default function SpinnerButton() {
  return (
    <Button disabled>
      <Spinner size="sm" className="text-primary-foreground" />
      Loading...
    </Button>
  );
}
```

## Styling

### Data Slots

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

| Slot name | Element          |
| --------- | ---------------- |
| `spinner` | The `<svg>` root |

### Customization Examples

```css
/* Change spinner color */
[data-slot="spinner"] {
  @apply text-primary;
}
```

```tsx
{
  /* Custom color via className */
}
<Spinner className="text-primary" size="lg" />;
```

## API Reference

### Spinner

An SVG loading spinner with rotation animation.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the spinner (sm=16px, md=24px, lg=32px). |
| `className` | `string` | - | Additional CSS classes. |

Extends `React.ComponentProps<"svg">`. All standard SVG props are forwarded via `...props`.

### spinnerVariants

A `cva` helper exported for use outside of the `<Spinner>` component.

## Accessibility

### Keyboard Interactions

Spinner is a non-interactive presentational element and does not have keyboard interactions.

### ARIA Attributes

- Add `role="status"` and `aria-label="Loading"` when the spinner indicates an ongoing operation.
- Use `aria-busy="true"` on the parent container while loading.

## Full Component Source

```tsx
"use client";

export { Spinner, spinnerVariants } from "@prototyperco/ui/components/spinner";
```
</component>

<component name="switch" url="https://prototyper-ui.com/docs/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`.

### SwitchTrack

The sliding track background container that holds the thumb.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Track size, defaults to size set on Switch root |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Content inside the track (typically SwitchThumb) |

All standard HTML `div` props are supported via `...props`.

### SwitchThumb

The circular thumb indicator that slides inside the track.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Content inside the thumb (typically SwitchIcon) |

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

### SwitchIcon

Optional icon wrapper for displaying icons inside the thumb.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Icon elements to display |

All standard HTML `span` props are supported via `...props`. The component automatically hides from screen readers with `aria-hidden="true"`.

## 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.

## Compose

This component is available in [`@prototyperco/compose`](/docs/compose).

### Catalog Definition

```typescript title="switch.catalog.ts"
import { z } from "zod";
import { defineComponent } from "@prototyperco/compose/catalog";

export default defineComponent({
  description: "A toggle switch for on/off states",
  props: z.object({
    label: z.string().optional().describe("Label displayed next to the switch"),
    checked: z.boolean().optional().describe("Whether the switch is on"),
    disabled: z.boolean().optional().describe("Whether the switch is disabled"),
    size: z.enum(["sm", "md", "lg"]).optional().describe("Switch size variant"),
  }),
  events: ["change"],
  example: { label: "Enable notifications", checked: false, size: "md" },
});
```

### Example Spec

```json
{
  "root": "notifSwitch",
  "elements": {
    "notifSwitch": {
      "type": "Switch",
      "props": {
        "label": "Enable notifications",
        "checked": false,
        "size": "md"
      },
      "$bindState": { "path": "/notificationsEnabled", "event": "change" }
    }
  }
}
```

Learn more in the [Compose documentation](/docs/compose).

## Full Component Source

```tsx
"use client";

export {
  Switch,
  SwitchTrack,
  SwitchThumb,
  SwitchIcon,
  switchVariants,
} from "@prototyperco/ui/components/switch";
```
</component>

<component name="tabs" url="https://prototyper-ui.com/docs/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() {
  const 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() {
  const [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" },
  ]);

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

  const 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/text-field";

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.

## Compose

This component is available in [`@prototyperco/compose`](/docs/compose).

### Catalog Definition

```typescript title="tabs.catalog.ts"
import { z } from "zod";
import { defineComponent } from "@prototyperco/compose/catalog";

export default defineComponent({
  description: "A tabbed interface for switching between content panels",
  props: z.object({
    tabs: z
      .array(
        z.object({
          label: z.string().describe("Tab button label"),
          value: z.string().describe("Tab identifier value"),
        }),
      )
      .describe("Tab definitions"),
    value: z.string().optional().describe("Active tab value (bindable)"),
    variant: z
      .enum(["default", "line"])
      .optional()
      .describe("Visual style variant"),
  }),
  events: ["change"],
  example: {
    tabs: [
      { label: "Account", value: "account" },
      { label: "Settings", value: "settings" },
      { label: "Billing", value: "billing" },
    ],
    value: "account",
  },
});
```

### Example Spec

```json
{
  "root": "tabsContainer",
  "elements": {
    "tabsContainer": {
      "type": "Tabs",
      "props": {
        "tabs": [
          { "label": "Account", "value": "account" },
          { "label": "Settings", "value": "settings" },
          { "label": "Billing", "value": "billing" }
        ],
        "value": "account"
      },
      "children": ["accountContent", "settingsContent", "billingContent"],
      "$bindState": { "path": "/activeTab", "event": "change" }
    },
    "accountContent": {
      "type": "Text",
      "props": { "content": "Manage your account details here." }
    },
    "settingsContent": {
      "type": "Text",
      "props": { "content": "Configure your preferences." }
    },
    "billingContent": {
      "type": "Text",
      "props": { "content": "View and manage your billing." }
    }
  }
}
```

Learn more in the [Compose documentation](/docs/compose).

## Full Component Source

```tsx
"use client";

export {
  Tabs,
  TabsList,
  TabsTrigger,
  TabsContent,
  tabsListVariants,
} from "@prototyperco/ui/components/tabs";
```

## All Examples

### tabs-line

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

export default function TabsLine() {
  return (
    <Tabs defaultValue="overview">
      <TabsList variant="line" aria-label="Project dashboard">
        <TabsTrigger value="overview">Overview</TabsTrigger>
        <TabsTrigger value="activity">Activity</TabsTrigger>
        <TabsTrigger value="settings">Settings</TabsTrigger>
      </TabsList>
      <TabsContent value="overview">
        A summary of your project status and key metrics.
      </TabsContent>
      <TabsContent value="activity">
        Recent commits, pull requests, and team updates.
      </TabsContent>
      <TabsContent value="settings">
        Configure repository access, webhooks, and integrations.
      </TabsContent>
    </Tabs>
  );
}
```

### tabs-settings

```tsx
import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/ui/tabs";
import { FieldLabel } from "@/components/ui/field";
import { Input, TextField } from "@/components/ui/text-field";
import { Button } from "@/components/ui/button";

export default function TabsSettings() {
  return (
    <Tabs defaultValue="account" className="w-full max-w-md">
      <TabsList aria-label="Settings">
        <TabsTrigger value="account">Account</TabsTrigger>
        <TabsTrigger value="password">Password</TabsTrigger>
      </TabsList>
      <TabsContent value="account">
        <form className="flex flex-col gap-4 pt-2">
          <TextField>
            <FieldLabel>Name</FieldLabel>
            <Input placeholder="Your name" />
          </TextField>
          <TextField>
            <FieldLabel>Email</FieldLabel>
            <Input type="email" placeholder="your@email.com" />
          </TextField>
          <Button type="submit" className="w-fit">
            Save changes
          </Button>
        </form>
      </TabsContent>
      <TabsContent value="password">
        <form className="flex flex-col gap-4 pt-2">
          <TextField>
            <FieldLabel>Current password</FieldLabel>
            <Input type="password" />
          </TextField>
          <TextField>
            <FieldLabel>New password</FieldLabel>
            <Input type="password" />
          </TextField>
          <Button type="submit" className="w-fit">
            Update password
          </Button>
        </form>
      </TabsContent>
    </Tabs>
  );
}
```

### tabs-with-icons

```tsx
import { Music, ImageIcon, Video } from "lucide-react";

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

export default function TabsWithIcons() {
  return (
    <Tabs defaultValue="music">
      <TabsList aria-label="Media library">
        <TabsTrigger value="music">
          <Music /> Music
        </TabsTrigger>
        <TabsTrigger value="photos">
          <ImageIcon /> Photos
        </TabsTrigger>
        <TabsTrigger value="videos">
          <Video /> Videos
        </TabsTrigger>
      </TabsList>
      <TabsContent value="music">
        Browse and manage your music collection.
      </TabsContent>
      <TabsContent value="photos">
        View, organize, and share your photo albums.
      </TabsContent>
      <TabsContent value="videos">
        Watch and manage your saved video clips.
      </TabsContent>
    </Tabs>
  );
}
```

</component>

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

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

## Installation

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

This will add the following files to your project:

- `components/ui/text-field.tsx`

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

## Usage

```tsx
import { TextField, Input } from "@/components/ui/text-field";
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/text-field";

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/text-field";

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/text-field";

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/text-field";

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

### Reusable

```tsx
import { ProtoTextField } from "@/components/ui/text-field";

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/text-field";

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/text-field";

<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.

## Full Component Source

```tsx
"use client";

export {
  Input,
  inputVariants,
  TextField,
  ProtoTextField,
  TextArea,
} from "@prototyperco/ui/components/text-field";
```
</component>

<component name="textarea" url="https://prototyper-ui.com/docs/components/textarea">
# Textarea
> a multi-line text input with validation styling
URL: https://prototyper-ui.com/docs/components/textarea
```tsx
import { Textarea } from "@/components/ui/textarea";

export default function TextareaDemo() {
  return <Textarea placeholder="Type your message here." />;
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/textarea.tsx`

## Usage

```tsx
import { Textarea } from "@/components/ui/textarea";
```

```tsx
<Textarea placeholder="Type your message here." />
```

## Styling

### Data Slots

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

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

### Customization Examples

```css
/* Make all textareas taller */
[data-slot="textarea"] {
  @apply min-h-32 text-lg;
}
```

```tsx
{
  /* Override styles via className */
}
<Textarea className="rounded-xl px-5" placeholder="Custom textarea" />;
```

## API Reference

### Textarea

A styled multi-line text input.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `placeholder` | `string` | - | Placeholder text shown when empty. |
| `className` | `string` | - | Additional CSS classes. |

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

## Accessibility

### Keyboard Interactions

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

### ARIA Attributes

- Renders as a native `<textarea>` element.
- `aria-invalid` styling is applied when the textarea has validation errors.
- Pair with a `<label>` or `aria-label` to ensure the textarea is accessible to screen readers.

## Compose

This component is available in [`@prototyperco/compose`](/docs/compose).

### Catalog Definition

```typescript title="textarea.catalog.ts"
import { z } from "zod";
import { defineComponent } from "@prototyperco/compose/catalog";

export default defineComponent({
  description: "A multi-line text area for longer form input",
  props: z.object({
    label: z.string().optional().describe("Label displayed above the textarea"),
    placeholder: z.string().optional().describe("Placeholder text"),
    value: z.string().optional().describe("Controlled textarea value"),
    rows: z.number().optional().describe("Number of visible text rows"),
    disabled: z
      .boolean()
      .optional()
      .describe("Whether the textarea is disabled"),
  }),
  events: ["change", "blur", "focus"],
  example: { label: "Message", placeholder: "Type your message...", rows: 3 },
});
```

### Example Spec

```json
{
  "root": "messageArea",
  "elements": {
    "messageArea": {
      "type": "Textarea",
      "props": {
        "label": "Message",
        "placeholder": "Type your message...",
        "rows": 3
      },
      "$bindState": { "path": "/message", "event": "change" }
    }
  }
}
```

Learn more in the [Compose documentation](/docs/compose).

## Full Component Source

```tsx
"use client";

export { Textarea } from "@prototyperco/ui/components/textarea";
```
</component>

<component name="toast" url="https://prototyper-ui.com/docs/components/toast">
# Toast
> notification system with type variants
URL: https://prototyper-ui.com/docs/components/toast
Base UI reference: https://base-ui.com/react/components/toast
```tsx
"use client";

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

export default function ToastDemo() {
  return (
    <Button
      variant="outline"
      onClick={() =>
        toast("Event has been created", {
          description: "Sunday, December 03, 2024 at 9:00 AM",
        })
      }
    >
      Show Toast
    </Button>
  );
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/toast.tsx`

### Setup

Wrap your application with `ToastProvider` in your root layout:

```tsx
import { ToastProvider } from "@/components/ui/toast";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <ToastProvider>{children}</ToastProvider>
      </body>
    </html>
  );
}
```

## Usage

```tsx
import { toast } from "@/components/ui/toast";

// Basic toast
toast("Event has been created");

// With description
toast("Event has been created", {
  description: "Sunday, December 03, 2024 at 9:00 AM",
});

// Typed variants
toast.success("Action completed successfully");
toast.error("Something went wrong");
toast.warning("Please review before continuing");
toast.info("A new update is available");
```

## Anatomy

```tsx
<ToastProvider>
  {/* Your app content */}
  {/* Toaster is rendered automatically inside ToastProvider */}
</ToastProvider>
```

The toast system consists of three layers:

| Export          | `data-slot` | Purpose                                                            | Required |
| --------------- | ----------- | ------------------------------------------------------------------ | -------- |
| `ToastProvider` | —           | Root provider that wraps your app, renders `Toaster` automatically | Yes      |
| `Toaster`       | `toaster`   | Viewport that positions and renders all active toasts              | Auto     |
| `toast`         | —           | Imperative API to create toasts from anywhere                      | Yes      |

Each individual toast renders the following structure:

| Part                | `data-slot`         | Purpose                                   |
| ------------------- | ------------------- | ----------------------------------------- |
| `Toast.Root`        | `toast`             | Container for a single toast notification |
| Icon                | `toast-icon`        | Type-specific icon (success, error, etc.) |
| Content wrapper     | `toast-content`     | Flex container for title and description  |
| `Toast.Title`       | `toast-title`       | Bold title text                           |
| `Toast.Description` | `toast-description` | Secondary description text                |
| `Toast.Action`      | `toast-action`      | Optional action button                    |
| `Toast.Close`       | `toast-close`       | Dismiss button                            |

## Examples

### Variants

```tsx
"use client";

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

export default function ToastVariants() {
  return (
    <div className="flex flex-wrap gap-2">
      <Button
        variant="outline"
        onClick={() => toast("This is a default toast")}
      >
        Default
      </Button>
      <Button
        variant="outline"
        onClick={() => toast.success("Action completed successfully")}
      >
        Success
      </Button>
      <Button
        variant="outline"
        onClick={() => toast.error("Something went wrong")}
      >
        Error
      </Button>
      <Button
        variant="outline"
        onClick={() => toast.warning("Please review before continuing")}
      >
        Warning
      </Button>
      <Button
        variant="outline"
        onClick={() => toast.info("A new update is available")}
      >
        Info
      </Button>
    </div>
  );
}
```

### With Action

```tsx
"use client";

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

export default function ToastAction() {
  return (
    <Button
      variant="outline"
      onClick={() =>
        toast("File deleted", {
          description: "The file has been moved to trash.",
          action: {
            label: "Undo",
            onClick: () => toast.success("File restored"),
          },
        })
      }
    >
      Show Toast with Action
    </Button>
  );
}
```

### Promise

```tsx
"use client";

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

export default function ToastPromise() {
  function handleClick() {
    const promise = new Promise<{ name: string }>((resolve) =>
      setTimeout(() => resolve({ name: "Prototyper UI" }), 2000),
    );

    toast.promise(promise, {
      loading: { title: "Loading..." },
      success: (data) => ({ title: `${data.name} has been added` }),
      error: { title: "Something went wrong" },
    });
  }

  return (
    <Button variant="outline" onClick={handleClick}>
      Show Promise Toast
    </Button>
  );
}
```

## Styling

### Data Slots

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

| Slot name           | Element                               |
| ------------------- | ------------------------------------- |
| `toaster`           | The viewport container for all toasts |
| `toast`             | Individual toast root                 |
| `toast-icon`        | Type-specific icon                    |
| `toast-content`     | Content wrapper (title + description) |
| `toast-title`       | Title text                            |
| `toast-description` | Description text                      |
| `toast-action`      | Action button                         |
| `toast-close`       | Dismiss button                        |

### Customization Examples

```css
/* Change toast position to top-center */
[data-slot="toaster"] {
  @apply bottom-auto top-4 right-auto left-1/2 -translate-x-1/2;
}

/* Wider toasts */
[data-slot="toaster"] {
  @apply w-[420px];
}

/* Custom success icon color */
[data-slot="toast-icon"] {
  @apply text-foreground;
}
```

```tsx
{
  /* Custom duration */
}
toast("Quick notification", { duration: 2000 });

{
  /* With action button */
}
toast("Item deleted", {
  action: {
    label: "Undo",
    onClick: () => console.log("Undo clicked"),
  },
});
```

## API Reference

### ToastProvider

Root provider that wraps your application. Renders the `Toaster` viewport automatically.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `React.ReactNode` | - | Your application content |

### toast(title, options?)

Imperative function to create a toast notification. Can be called from anywhere in your app.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | - | The toast title text |

### toast.success / toast.error / toast.warning / toast.info

Typed variants that display a corresponding icon. Accept the same `(title, options?)` signature as `toast()`.

| Method          | Icon                | Color       |
| --------------- | ------------------- | ----------- |
| `toast.success` | `CircleCheckIcon`   | Emerald 500 |
| `toast.error`   | `OctagonXIcon`      | Red 500     |
| `toast.warning` | `TriangleAlertIcon` | Amber 500   |
| `toast.info`    | `InfoIcon`          | Blue 500    |

### toast.promise(promise, options)

Tracks a promise and shows loading, success, and error states.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `promise` | `Promise<T>` | - | The promise to track |

### Toaster

The viewport component that renders all active toasts. Rendered automatically by `ToastProvider`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | CSS class name for the viewport container |

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

## Accessibility

### Keyboard Interactions

| Key      | Action                      |
| -------- | --------------------------- |
| `Escape` | Dismisses all active toasts |

### ARIA Attributes

- Each toast is rendered as an ARIA live region via Base UI's `Toast.Root`.
- `Toast.Title` is used as the accessible label for the toast.
- `Toast.Description` provides additional context.
- `Toast.Close` includes `aria-label="Dismiss"` for screen readers.
- Toasts support swipe-to-dismiss gestures on touch devices.
- Motion is reduced when the user has `prefers-reduced-motion` enabled.

### Screen Reader Behavior

- New toasts are announced automatically via ARIA live regions.
- The `Toast.Action` button is focusable and announced with its label.
- The close button announces "Dismiss" to assistive technology.

## Full Component Source

```tsx
"use client";

export {
  ToastProvider,
  Toaster,
  toast,
} from "@prototyperco/ui/components/toast";
```
</component>

<component name="toggle" url="https://prototyper-ui.com/docs/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 { Bold } from "lucide-react";

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

export default function ToggleDemo() {
  return (
    <Toggle aria-label="Toggle italic">
      <Bold 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 { Italic } from "lucide-react";

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

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

### Small

```tsx
import { Italic } from "lucide-react";

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

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

### Large

```tsx
import { Italic } from "lucide-react";

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

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

### Disabled

```tsx
import { Underline } from "lucide-react";

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

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

### With Text

```tsx
import { Italic } from "lucide-react";

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

export default function ToggleWithText() {
  return (
    <Toggle aria-label="Toggle italic">
      <Italic 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.

## Full Component Source

```tsx
"use client";

export { Toggle, toggleVariants } from "@prototyperco/ui/components/toggle";
```
</component>

<component name="toggle-group" url="https://prototyper-ui.com/docs/components/toggle-group">
# Toggle Group
> group of toggles with single or multiple selection
URL: https://prototyper-ui.com/docs/components/toggle-group
Base UI reference: https://base-ui.com/react/components/toggle-group
```tsx
import { AlignCenter, AlignLeft, AlignRight } from "lucide-react";

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

export default function ToggleGroupDemo() {
  return (
    <ToggleGroup defaultValue={["center"]} aria-label="Text alignment">
      <ToggleGroupItem value="left" aria-label="Align left">
        <AlignLeft className="size-4" />
      </ToggleGroupItem>
      <ToggleGroupItem value="center" aria-label="Align center">
        <AlignCenter className="size-4" />
      </ToggleGroupItem>
      <ToggleGroupItem value="right" aria-label="Align right">
        <AlignRight className="size-4" />
      </ToggleGroupItem>
    </ToggleGroup>
  );
}
```

## Installation

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

This will add the following files to your project:

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

## Usage

```tsx
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

<ToggleGroup defaultValue={["center"]} aria-label="Text alignment">
  <ToggleGroupItem value="left" aria-label="Align left">
    Left
  </ToggleGroupItem>
  <ToggleGroupItem value="center" aria-label="Align center">
    Center
  </ToggleGroupItem>
  <ToggleGroupItem value="right" aria-label="Align right">
    Right
  </ToggleGroupItem>
</ToggleGroup>;
```

## Anatomy

```tsx
<ToggleGroup>
  <ToggleGroupItem />
  <ToggleGroupItem />
  <ToggleGroupItem />
</ToggleGroup>
```

| Sub-component     | `data-slot`         | Purpose                                   | Required |
| ----------------- | ------------------- | ----------------------------------------- | -------- |
| `ToggleGroup`     | `toggle-group`      | Root container, manages selection state   | Yes      |
| `ToggleGroupItem` | `toggle-group-item` | Individual toggle button within the group | Yes      |

## Examples

### Outline

```tsx
import { AlignCenter, AlignLeft, AlignRight } from "lucide-react";

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

export default function ToggleGroupOutline() {
  return (
    <ToggleGroup
      variant="outline"
      defaultValue={["left"]}
      aria-label="Text alignment"
    >
      <ToggleGroupItem value="left" aria-label="Align left">
        <AlignLeft className="size-4" />
      </ToggleGroupItem>
      <ToggleGroupItem value="center" aria-label="Align center">
        <AlignCenter className="size-4" />
      </ToggleGroupItem>
      <ToggleGroupItem value="right" aria-label="Align right">
        <AlignRight className="size-4" />
      </ToggleGroupItem>
    </ToggleGroup>
  );
}
```

### Multiple

```tsx
import { Bold, Italic, Strikethrough, Underline } from "lucide-react";

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

export default function ToggleGroupMultiple() {
  return (
    <ToggleGroup
      multiple
      defaultValue={["bold", "italic"]}
      aria-label="Text formatting"
    >
      <ToggleGroupItem value="bold" aria-label="Bold">
        <Bold className="size-4" />
      </ToggleGroupItem>
      <ToggleGroupItem value="italic" aria-label="Italic">
        <Italic className="size-4" />
      </ToggleGroupItem>
      <ToggleGroupItem value="underline" aria-label="Underline">
        <Underline className="size-4" />
      </ToggleGroupItem>
      <ToggleGroupItem value="strikethrough" aria-label="Strikethrough">
        <Strikethrough className="size-4" />
      </ToggleGroupItem>
    </ToggleGroup>
  );
}
```

### Vertical

```tsx
import { AlignCenter, AlignJustify, AlignLeft, AlignRight } from "lucide-react";

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

export default function ToggleGroupVertical() {
  return (
    <ToggleGroup
      orientation="vertical"
      defaultValue={["left"]}
      aria-label="Text alignment"
    >
      <ToggleGroupItem value="left" aria-label="Align left">
        <AlignLeft className="size-4" />
      </ToggleGroupItem>
      <ToggleGroupItem value="center" aria-label="Align center">
        <AlignCenter className="size-4" />
      </ToggleGroupItem>
      <ToggleGroupItem value="right" aria-label="Align right">
        <AlignRight className="size-4" />
      </ToggleGroupItem>
      <ToggleGroupItem value="justify" aria-label="Justify">
        <AlignJustify className="size-4" />
      </ToggleGroupItem>
    </ToggleGroup>
  );
}
```

### Small

```tsx
import { AlignCenter, AlignLeft, AlignRight } from "lucide-react";

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

export default function ToggleGroupSm() {
  return (
    <ToggleGroup
      size="sm"
      defaultValue={["center"]}
      aria-label="Text alignment"
    >
      <ToggleGroupItem value="left" aria-label="Align left">
        <AlignLeft className="size-4" />
      </ToggleGroupItem>
      <ToggleGroupItem value="center" aria-label="Align center">
        <AlignCenter className="size-4" />
      </ToggleGroupItem>
      <ToggleGroupItem value="right" aria-label="Align right">
        <AlignRight className="size-4" />
      </ToggleGroupItem>
    </ToggleGroup>
  );
}
```

### Large

```tsx
import { AlignCenter, AlignLeft, AlignRight } from "lucide-react";

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

export default function ToggleGroupLg() {
  return (
    <ToggleGroup
      size="lg"
      defaultValue={["center"]}
      aria-label="Text alignment"
    >
      <ToggleGroupItem value="left" aria-label="Align left">
        <AlignLeft className="size-4" />
      </ToggleGroupItem>
      <ToggleGroupItem value="center" aria-label="Align center">
        <AlignCenter className="size-4" />
      </ToggleGroupItem>
      <ToggleGroupItem value="right" aria-label="Align right">
        <AlignRight className="size-4" />
      </ToggleGroupItem>
    </ToggleGroup>
  );
}
```

### Disabled

```tsx
import { AlignCenter, AlignLeft, AlignRight } from "lucide-react";

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

export default function ToggleGroupDisabled() {
  return (
    <ToggleGroup disabled defaultValue={["left"]} aria-label="Text alignment">
      <ToggleGroupItem value="left" aria-label="Align left">
        <AlignLeft className="size-4" />
      </ToggleGroupItem>
      <ToggleGroupItem value="center" aria-label="Align center">
        <AlignCenter className="size-4" />
      </ToggleGroupItem>
      <ToggleGroupItem value="right" aria-label="Align right">
        <AlignRight className="size-4" />
      </ToggleGroupItem>
    </ToggleGroup>
  );
}
```

## Styling

### Data Slots

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

| Slot name           | Element                             |
| ------------------- | ----------------------------------- |
| `toggle-group`      | Root container for all toggle items |
| `toggle-group-item` | Individual toggle button            |

### Customization Examples

```css
/* Style all pressed items in a toggle group */
[data-slot="toggle-group-item"][data-state="on"] {
  @apply bg-primary text-primary-foreground;
}

/* Add spacing between items */
[data-slot="toggle-group"] {
  @apply gap-1;
}
```

```tsx
{
  /* Override styles via className */
}
<ToggleGroup className="rounded-lg border bg-background p-1">
  <ToggleGroupItem value="a">A</ToggleGroupItem>
  <ToggleGroupItem value="b">B</ToggleGroupItem>
</ToggleGroup>;
```

## API Reference

### ToggleGroup

Root container that manages which toggle items are pressed.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string[]` | - | Controlled pressed values |
| `defaultValue` | `string[]` | - | Initial pressed values for uncontrolled usage |
| `onValueChange` | `(value: string[]) => void` | - | Callback when pressed values change |
| `multiple` | `boolean` | `false` | Whether multiple items can be pressed simultaneously |
| `disabled` | `boolean` | `false` | Whether all toggle items are disabled |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Layout direction of the toggle group |
| `variant` | `"default" \| "outline"` | `"default"` | Visual style variant applied to all items |
| `size` | `"default" \| "sm" \| "lg"` | `"default"` | Size applied to all items |
| `spacing` | `number` | `0` | Gap between items (0 creates a joined look) |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Toggle group content |

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

### ToggleGroupItem

An individual toggle button within the group.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | - | Unique value for this toggle item (required) |
| `variant` | `"default" \| "outline"` | `"default"` | Visual style variant (overridden by group variant) |
| `size` | `"default" \| "sm" \| "lg"` | `"default"` | Size of the toggle item (overridden by group size) |
| `disabled` | `boolean` | `false` | Whether this individual item is disabled |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Toggle item content |

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

## Accessibility

### Keyboard Interactions

| Key          | Action                                                    |
| ------------ | --------------------------------------------------------- |
| `Space`      | Toggles the pressed state of the focused item             |
| `Enter`      | Toggles the pressed state of the focused item             |
| `Tab`        | Moves focus into / out of the toggle group                |
| `ArrowRight` | Moves focus to the next item (horizontal orientation)     |
| `ArrowLeft`  | Moves focus to the previous item (horizontal orientation) |
| `ArrowDown`  | Moves focus to the next item (vertical orientation)       |
| `ArrowUp`    | Moves focus to the previous item (vertical orientation)   |
| `Home`       | Moves focus to the first item                             |
| `End`        | Moves focus to the last item                              |

### ARIA Attributes

- `ToggleGroup` renders as a `group` with `aria-label` describing the group purpose.
- Each `ToggleGroupItem` renders as a `<button>` with `aria-pressed` attribute.
- `aria-pressed="true"` when the item is in the pressed state, `aria-pressed="false"` when unpressed.
- `aria-disabled` is set when the group or an individual item is disabled.
- `aria-orientation` is set to match the `orientation` prop.
- Focus management follows the roving tabindex pattern so only one item is tabbable at a time.

## Full Component Source

```tsx
"use client";

export {
  ToggleGroup,
  ToggleGroupItem,
} from "@prototyperco/ui/components/toggle-group";
```
</component>

<component name="toolbar" url="https://prototyper-ui.com/docs/components/toolbar">
# Toolbar
> A toolbar 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 { Bold, Italic, Underline } from "lucide-react";
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">
          <Bold className="size-4" />
        </Toggle>
        <Toggle className="w-10" variant="outline" aria-label="Italic">
          <Italic className="size-4" />
        </Toggle>
        <Toggle className="w-10" variant="outline" aria-label="Underline">
          <Underline 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 { MousePointer, Move, PenLine, Pencil, Wand2 } from "lucide-react";
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">
          <Move className="size-4" />
        </Button>
        <Button variant="outline" size="icon" aria-label="Rectangle">
          <MousePointer className="size-4" />
        </Button>
        <Button variant="outline" size="icon" aria-label="Polygon">
          <Wand2 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">
          <PenLine className="size-4" />
        </Button>
        <Button variant="outline" size="icon" aria-label="Pencil">
          <Pencil 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.

## Full Component Source

```tsx
"use client";

export {
  Toolbar,
  ToolbarButton,
  ToolbarLink,
  ToolbarGroup,
  ToolbarSeparator,
  ToolbarInput,
} from "@prototyperco/ui/components/toolbar";
```
</component>

<component name="tooltip" url="https://prototyper-ui.com/docs/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 { PencilIcon } from "lucide-react";

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" />}
      >
        <PencilIcon 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 "lucide-react";

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 { PencilIcon } from "lucide-react";

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" />}
      >
        <PencilIcon className="size-4" />
      </TooltipTrigger>
      <TooltipContent>Edit</TooltipContent>
    </Tooltip>
  );
}
```

### Offset

```tsx
import { ArrowUpIcon } from "lucide-react";

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.

## Compose

This component is available in [`@prototyperco/compose`](/docs/compose).

### Catalog Definition

```typescript title="tooltip.catalog.ts"
import { z } from "zod";
import { defineComponent } from "@prototyperco/compose/catalog";

export default defineComponent({
  description:
    "A tooltip that displays informational text when hovering over its trigger content",
  props: z.object({
    content: z.string().describe("Tooltip text to display on hover"),
  }),
  events: [],
  example: { content: "More information" },
});
```

### Example Spec

```json
{
  "root": "tip",
  "elements": {
    "tip": {
      "type": "Tooltip",
      "props": {
        "content": "More information"
      },
      "children": ["triggerBtn"]
    },
    "triggerBtn": {
      "type": "Button",
      "props": { "label": "Hover me", "variant": "outline" }
    }
  }
}
```

Learn more in the [Compose documentation](/docs/compose).

## Full Component Source

```tsx
"use client";

export {
  Tooltip,
  TooltipTrigger,
  TooltipContent,
  TooltipProvider,
} from "@prototyperco/ui/components/tooltip";
```
</component>

<component name="tree-view" url="https://prototyper-ui.com/docs/components/tree-view">
# Tree View
> A hierarchical tree view with collapsible nodes and keyboard navigation built on Base UI
URL: https://prototyper-ui.com/docs/components/tree-view
Base UI reference: https://base-ui.com/react/components/collapsible
```tsx
import {
  TreeView,
  TreeViewItem,
  TreeViewGroup,
  TreeViewLeaf,
} from "@/components/ui/tree-view";

export default function TreeViewDemo() {
  return (
    <TreeView className="w-64 rounded-lg border border-border p-2">
      <TreeViewItem itemKey="src" label="src">
        <TreeViewGroup>
          <TreeViewItem itemKey="components" label="components">
            <TreeViewGroup>
              <TreeViewLeaf>button.tsx</TreeViewLeaf>
              <TreeViewLeaf>dialog.tsx</TreeViewLeaf>
              <TreeViewLeaf>input.tsx</TreeViewLeaf>
            </TreeViewGroup>
          </TreeViewItem>
          <TreeViewItem itemKey="lib" label="lib">
            <TreeViewGroup>
              <TreeViewLeaf>utils.ts</TreeViewLeaf>
            </TreeViewGroup>
          </TreeViewItem>
          <TreeViewLeaf>app.tsx</TreeViewLeaf>
          <TreeViewLeaf>index.tsx</TreeViewLeaf>
        </TreeViewGroup>
      </TreeViewItem>
      <TreeViewItem itemKey="public" label="public">
        <TreeViewGroup>
          <TreeViewLeaf>favicon.ico</TreeViewLeaf>
          <TreeViewLeaf>index.html</TreeViewLeaf>
        </TreeViewGroup>
      </TreeViewItem>
      <TreeViewLeaf>package.json</TreeViewLeaf>
      <TreeViewLeaf>tsconfig.json</TreeViewLeaf>
    </TreeView>
  );
}
```

## Installation

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

This will add the following files to your project:

- `components/ui/tree-view.tsx`

## Usage

```tsx
import {
  TreeView,
  TreeViewItem,
  TreeViewGroup,
  TreeViewLeaf,
} from "@/components/ui/tree-view";

<TreeView>
  <TreeViewItem itemKey="src" label="src">
    <TreeViewGroup>
      <TreeViewLeaf>index.tsx</TreeViewLeaf>
      <TreeViewLeaf>app.tsx</TreeViewLeaf>
    </TreeViewGroup>
  </TreeViewItem>
  <TreeViewLeaf>package.json</TreeViewLeaf>
</TreeView>;
```

## Anatomy

```tsx
<TreeView>
  <TreeViewItem itemKey="..." label="...">
    <TreeViewGroup>
      <TreeViewItem itemKey="..." label="...">
        <TreeViewGroup>
          <TreeViewLeaf />
        </TreeViewGroup>
      </TreeViewItem>
      <TreeViewLeaf />
    </TreeViewGroup>
  </TreeViewItem>
</TreeView>
```

| Sub-component   | `data-slot`       | Purpose                                     | Required |
| --------------- | ----------------- | ------------------------------------------- | -------- |
| `TreeView`      | `tree-view`       | Root container with keyboard navigation     | Yes      |
| `TreeViewItem`  | `tree-view-item`  | Collapsible node with chevron and label     | Yes      |
| `TreeViewGroup` | `tree-view-group` | Animated collapsible container for children | Yes      |
| `TreeViewLeaf`  | `tree-view-leaf`  | Terminal node (no children)                 | No       |

## Examples

### Default expanded

```tsx
<TreeView defaultExpandAll>
  <TreeViewItem itemKey="docs" label="docs">
    <TreeViewGroup>
      <TreeViewLeaf>getting-started.md</TreeViewLeaf>
      <TreeViewLeaf>api-reference.md</TreeViewLeaf>
    </TreeViewGroup>
  </TreeViewItem>
</TreeView>
```

### Controlled expanded keys

```tsx
const [expandedKeys, setExpandedKeys] = useState(new Set(["src"]))

<TreeView expandedKeys={expandedKeys} onExpandedKeysChange={setExpandedKeys}>
  <TreeViewItem itemKey="src" label="src">
    <TreeViewGroup>
      <TreeViewLeaf>index.tsx</TreeViewLeaf>
    </TreeViewGroup>
  </TreeViewItem>
</TreeView>
```

## Styling

### Data Slots

| Slot name              | Element                                 |
| ---------------------- | --------------------------------------- |
| `tree-view`            | Root `div` with `role="tree"`           |
| `tree-view-item`       | Collapsible node row with chevron       |
| `tree-view-item-icon`  | Chevron icon (rotates when expanded)    |
| `tree-view-item-label` | Label text                              |
| `tree-view-group`      | Animated collapsible panel for children |
| `tree-view-leaf`       | Terminal item row                       |

### Customization Examples

```css
/* Custom item hover color */
[data-slot="tree-view-item"]:hover,
[data-slot="tree-view-leaf"]:hover {
  @apply bg-primary/10;
}

/* Custom chevron color */
[data-slot="tree-view-item-icon"] {
  @apply text-primary;
}
```

## API Reference

### TreeView

Root container that provides context, keyboard navigation, and expanded state management.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `expandedKeys` | `Set<string>` | - | Controlled set of expanded item keys |
| `onExpandedKeysChange` | `(keys: Set<string>) => void` | - | Callback when expanded keys change |
| `defaultExpandedKeys` | `Set<string>` | - | Default expanded keys (uncontrolled) |
| `defaultExpandAll` | `boolean` | `false` | Expand all nodes by default |
| `className` | `string` | - | Additional CSS classes |

All standard `div` props are forwarded.

### TreeViewItem

Collapsible node with a chevron icon and label. Uses Base UI `Collapsible.Root` internally.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `itemKey` | `string` | - | Unique key for this item (used for expand/collapse tracking) |
| `label` | `React.ReactNode` | - | Label content displayed next to the chevron |
| `depth` | `number` | - | Depth level (auto-managed, can override) |
| `className` | `string` | - | Additional CSS classes |

All standard `div` props are forwarded.

### TreeViewGroup

Animated collapsible container for child items. Uses Base UI `Collapsible.Panel`.

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

All standard `div` props are forwarded.

### TreeViewLeaf

Terminal node (no children). Renders with extra left padding to align with item labels.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `depth` | `number` | - | Depth level (auto-managed, can override) |
| `className` | `string` | - | Additional CSS classes |

All standard `div` props are forwarded.

## Accessibility

### Keyboard Interactions

| Key             | Action                                                        |
| --------------- | ------------------------------------------------------------- |
| `ArrowDown`     | Moves focus to the next visible item                          |
| `ArrowUp`       | Moves focus to the previous visible item                      |
| `ArrowRight`    | Expands a collapsed item, or moves to first child if expanded |
| `ArrowLeft`     | Collapses an expanded item, or moves to parent                |
| `Home`          | Moves focus to the first visible item                         |
| `End`           | Moves focus to the last visible item                          |
| `Enter`/`Space` | Toggles expand/collapse on a tree item                        |

### ARIA Attributes

- The root element has `role="tree"`.
- Each `TreeViewItem` and `TreeViewLeaf` has `role="treeitem"`.
- `TreeViewItem` has `aria-expanded` reflecting its expand state.
- `TreeViewGroup` has `role="group"`.
- Depth-based indentation provides visual hierarchy.

## Full Component Source

```tsx
"use client";

export {
  TreeView,
  TreeViewItem,
  TreeViewGroup,
  TreeViewLeaf,
} from "@prototyperco/ui/components/tree-view";
```
</component>