# BlankUI: full docs for agents

## BlankUI

This project uses [BlankUI](https://blank.vageshwar.dev). Components live in `components/ui`. Each one has a `.md` file next to it that says when to use it and what to avoid. Read it before using a component for the first time.

Rules:

- Stack is React 19 and Tailwind CSS v4. Do not use `forwardRef` or `tailwind.config.js`.
- Colors come from semantic tokens only: `bg-background`, `bg-surface`, `bg-surface-hover`, `bg-primary`, `text-primary-foreground`, `text-foreground`, `text-muted-foreground`, `border-border`, `bg-destructive`, `bg-success`, `bg-warning`. The Tailwind palette (`bg-blue-500`, `text-white`) does not exist in this project.
- No arbitrary values like `mt-[13px]`, `w-[372px]` or `bg-[#fff]`.
- Spacing between elements uses `Stack`, `Inline`, `Grid` and `Container` with `gap` 1, 2, 3, 4, 6, 8 or 12. Do not use `space-y-*`, `space-x-*` or `flex gap-*` for layout.
- Use BlankUI components instead of raw `<button>`, `<input>`, `<select>`, `<textarea>` and `<table>`.
- Every form control goes inside `<Field label="...">`, which wires the label, help text and errors.
- `DialogContent`, `SheetContent` and `AlertDialogContent` take a `title` prop. There is no `DialogTitle`.
- Icon-only buttons need `aria-label`: `<Button size="icon" aria-label="Close"><X /></Button>`.
- Icons come from `lucide-react` only.
- Do not edit files in `components/ui` to change a single usage. Add a variant there, or use the component as documented.
- Run the linter after changes. BlankUI lint messages say what to use instead.
- If a component you need is not in `components/ui`, add it with `npx blankui add <name>` instead of building your own.

Components:

| Component | Use for | Import |
| --- | --- | --- |
| AlertDialog, AlertDialogTrigger, AlertDialogContent, AlertDialogFooter | Confirming a delete or another action that cannot be undone. | `@/components/ui/alert-dialog` |
| Button | Trigger an action like save, submit, delete or open a dialog. | `@/components/ui/button` |
| Card, CardHeader, CardTitle, CardDescription | Group related content, like a settings section or a summary. | `@/components/ui/card` |
| Checkbox | A single yes or no choice, like agreeing to terms. | `@/components/ui/checkbox` |
| Dialog, DialogTrigger, DialogContent, DialogFooter | A short focused task, like editing a profile or creating an item. | `@/components/ui/dialog` |
| Field, useFieldControl | Every form control that needs a visible label. That is almost all of them. | `@/components/ui/field` |
| Input | Short text like a name, email, password, number or URL. | `@/components/ui/input` |
| Stack, Inline, Grid, Container | Any vertical list of elements with space between them (Stack). | `@/components/ui/layout` |
| Popover, PopoverTrigger, PopoverContent | A few extra controls next to a button, like share settings or a date picker. | `@/components/ui/popover` |
| Select, SelectTrigger, SelectValue, SelectContent | Picking one option from a list of about 4 to 20 items. | `@/components/ui/select` |
| Sheet, SheetTrigger, SheetContent, SheetFooter | Filters or settings next to a list the user still wants to see. | `@/components/ui/sheet` |
| Table, TableHeader, TableBody, TableRow | Rows of records with the same columns that people compare or scan. | `@/components/ui/table` |
| Tabs, TabsList, TabsTrigger, TabsContent | Two to six views of related content where the user looks at one at a time. | `@/components/ui/tabs` |
| Textarea | Text that can span several lines, like a message, bio or description. | `@/components/ui/textarea` |
| Toaster, toast | Confirming an action finished, like saving or copying. | `@/components/ui/toast` |
| Tooltip, TooltipTrigger, TooltipContent | Naming an icon-only button for sighted users. | `@/components/ui/tooltip` |

Full docs for agents: https://blank.vageshwar.dev/llms-full.txt

---
# Alert Dialog

`title` and `description` are both required. Cancel gets focus when it opens, so pressing Enter by accident does not confirm.

## Import

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

## Example

```tsx
<AlertDialog>
  <AlertDialogTrigger asChild>
    <Button variant="destructive">Delete project</Button>
  </AlertDialogTrigger>
  <AlertDialogContent
    title="Delete this project?"
    description="All files and settings will be removed. This cannot be undone."
  >
    <AlertDialogFooter>
      <AlertDialogCancel>Cancel</AlertDialogCancel>
      <AlertDialogAction destructive onClick={deleteProject}>
        Delete
      </AlertDialogAction>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>
```
### When not to use

- A task with form fields. Use dialog.
- The action can be undone easily. Use toast.
### Mistakes to avoid

- Avoid `window.confirm('Are you sure?')`. Instead: `<AlertDialog>`
- Avoid `<AlertDialogAction className="bg-destructive">`. Instead: `<AlertDialogAction destructive>`
- Avoid `A vague title like "Are you sure?"`. Instead: `Name the action: "Delete this project?"`
---
# Button

## Import

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

## Variants

| Variant       | Use for                                       |
| ------------- | --------------------------------------------- |
| `default`     | The main action in a view. One per view.      |
| `secondary`   | A second, less important action.              |
| `outline`     | Cancel, back, and other neutral actions.      |
| `ghost`       | Toolbar and icon actions with little weight.  |
| `destructive` | Delete or other actions that cannot be undone |
| `link`        | An action that should look like a link.       |

Sizes: `sm`, `default`, `lg`, `icon`.

## Examples

```tsx
<Inline gap={2} justify="end">
  <Button variant="outline">Cancel</Button>
  <Button type="submit" loading={isSaving}>
    Save changes
  </Button>
</Inline>
```

Icon buttons must have an `aria-label`. TypeScript reports an error without it.

```tsx
import { Trash } from "lucide-react"

;<Button size="icon" variant="ghost" aria-label="Delete project">
  <Trash />
</Button>
```

Icons next to text go before the text:

```tsx
import { Plus } from "lucide-react"

;<Button>
  <Plus /> New project
</Button>
```

Links that look like buttons:

```tsx
<Button asChild variant="outline">
  <a href="/pricing">See pricing</a>
</Button>
```

## Notes

- `type` defaults to `"button"`, so a Button inside a form does not submit it. Use `type="submit"` for the submit button.
- `loading` shows a spinner, disables the button and sets `aria-busy`.
### When not to use

- Navigating to another page inside text. Use a plain link (<a> or your router's Link).
- Switching between views of the same content. Use tabs.
- Toggling a setting on or off. Use checkbox.
### Mistakes to avoid

- Avoid `<button className=...> (a raw button element)`. Instead: `<Button>`
- Avoid `<Button className="bg-red-500">`. Instead: `<Button variant="destructive">`
- Avoid `<Button size="icon"><Trash /></Button> without a label`. Instead: `<Button size="icon" aria-label="Delete"><Trash /></Button>`
- Avoid `<Button><a href=...>Docs</a></Button> (a link inside a button)`. Instead: `<Button asChild><a href="/docs">Docs</a></Button>`
- Avoid `{isSaving ? <Spinner /> : 'Save'} with disabled={isSaving}`. Instead: `<Button loading={isSaving}>Save</Button>`
- Avoid `Several default (primary) buttons side by side`. Instead: `One default button, the rest variant="outline" or "ghost"`
---
# Card

## Import

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

## Example

```tsx
<Card>
  <CardHeader>
    <CardTitle>Notifications</CardTitle>
    <CardDescription>Choose what you want to hear about.</CardDescription>
  </CardHeader>
  <CardContent>
    <Stack gap={3}>...</Stack>
  </CardContent>
  <CardFooter>
    <Button>Save</Button>
  </CardFooter>
</Card>
```

## Card grid

```tsx
<Grid columns={{ base: 1, md: 3 }} gap={6}>
  {plans.map((plan) => (
    <Card key={plan.id}>
      <CardHeader>
        <CardTitle>{plan.name}</CardTitle>
        <CardDescription>{plan.price}</CardDescription>
      </CardHeader>
    </Card>
  ))}
</Grid>
```

## Notes

- `CardTitle` renders an `h3`. Use `asChild` to pick another heading level: `<CardTitle asChild><h2>Billing</h2></CardTitle>`.
- Every part already has padding and spacing. Do not add `p-*` classes.
### When not to use

- You only need space between elements. Use layout.
- Content should block the page until the user responds. Use dialog.
- Showing rows of data with the same fields. Use table.
### Mistakes to avoid

- Avoid `<div className="rounded-lg border p-6 shadow">`. Instead: `<Card>`
- Avoid `A Card inside another Card`. Instead: `Use a Stack inside one Card, or separate Cards in a Grid`
- Avoid `<CardContent className="p-6"> (adding padding)`. Instead: `<CardContent> already has padding`
---
# Checkbox

Built on Radix. Use `checked` and `onCheckedChange`, not `onChange`. The value can be `true`, `false` or `"indeterminate"`.

## Import

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

## Example

```tsx
<Field label="Send me product updates" orientation="horizontal">
  <Checkbox checked={updates} onCheckedChange={(checked) => setUpdates(checked === true)} />
</Field>
```

## In a form

```tsx
<Field label="I agree to the terms" orientation="horizontal" required>
  <Checkbox name="terms" value="yes" />
</Field>
```
### When not to use

- Picking exactly one option from a list. Use select.
- Triggering an action right away. Use button.
### Mistakes to avoid

- Avoid `<input type="checkbox">`. Instead: `<Checkbox>`
- Avoid `onChange={(e) => setValue(e.target.checked)}`. Instead: `onCheckedChange={(checked) => setValue(checked === true)}`
- Avoid `<Field label="..."> (vertical) around a Checkbox`. Instead: `<Field label="..." orientation="horizontal">`
---
# Dialog

The title is a prop on `DialogContent`, so a dialog can never be missing its accessible name. BlankUI does not export `DialogHeader`, `DialogTitle` or `DialogDescription`.

## Import

```tsx
import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogFooter,
  DialogTrigger,
} from "@/components/ui/dialog"
```

## Example

```tsx
<Dialog>
  <DialogTrigger asChild>
    <Button>Edit profile</Button>
  </DialogTrigger>
  <DialogContent title="Edit profile" description="Changes are saved when you click Save.">
    <Stack gap={4}>
      <Field label="Name">
        <Input defaultValue="Ada" />
      </Field>
    </Stack>
    <DialogFooter>
      <DialogClose asChild>
        <Button variant="outline">Cancel</Button>
      </DialogClose>
      <Button type="submit">Save</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>
```

## Controlled

```tsx
const [open, setOpen] = useState(false)

<Dialog open={open} onOpenChange={setOpen}>
  <DialogContent title="Invite people">...</DialogContent>
</Dialog>
```

## DialogContent props

- `title` (required), `description`
- `hideTitle`: keeps the title for screen readers only
- `size`: `sm`, `md` (default), `lg`
- `showCloseButton`: defaults to `true`
### When not to use

- Asking the user to confirm a destructive or important action. Use alert-dialog.
- Long forms, filters or navigation that work better at the edge of the screen. Use sheet.
- A few extra controls next to a button, without blocking the page. Use popover.
- A short text hint on hover. Use tooltip.
- Telling the user something happened. Use toast.
### Mistakes to avoid

- Avoid `<DialogHeader><DialogTitle>...</DialogTitle></DialogHeader> (shadcn style)`. Instead: `<DialogContent title="..." description="..."> (BlankUI renders the header)`
- Avoid `A Dialog with no visible title`. Instead: `<DialogContent title="Search" hideTitle> keeps it for screen readers`
- Avoid `Using Dialog to confirm a delete`. Instead: `<AlertDialog>`
- Avoid `<DialogClose><Button>Cancel</Button></DialogClose> (a button inside a button)`. Instead: `<DialogClose asChild><Button variant="outline">Cancel</Button></DialogClose>`
---
# Field

Field renders the label, help text and error for one control, and passes `id`, `aria-describedby`, `aria-invalid` and `required` to the control inside it. Input, Textarea, Select and Checkbox all read this automatically.

## Import

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

## Example

```tsx
<form onSubmit={handleSubmit}>
  <Stack gap={4}>
    <Field label="Email" description="We never share your email." error={errors.email} required>
      <Input type="email" name="email" />
    </Field>
    <Field label="Plan">
      <Select name="plan" defaultValue="pro">
        <SelectTrigger>
          <SelectValue />
        </SelectTrigger>
        <SelectContent>
          <SelectItem value="free">Free</SelectItem>
          <SelectItem value="pro">Pro</SelectItem>
        </SelectContent>
      </Select>
    </Field>
    <Field label="I agree to the terms" orientation="horizontal">
      <Checkbox name="terms" />
    </Field>
    <Button type="submit">Create account</Button>
  </Stack>
</form>
```

## With react-hook-form

```tsx
const { register, formState: { errors } } = useForm<FormValues>()

<Field label="Name" error={errors.name?.message} required>
  <Input {...register("name", { required: "Name is required" })} />
</Field>
```

## Props

- `label` (required): visible label text.
- `description`: help text under the label.
- `error`: error message. Marks the control invalid.
- `required`: marks the control required and shows `*`.
- `orientation`: `vertical` (default) or `horizontal`. Use `horizontal` for Checkbox.
- `id`: control id. Generated when not set.

## Building a new control

Call `useFieldControl(props)` in your control and spread the result onto the element. It adds the Field wiring and keeps any props you set directly.
### When not to use

- A search box in a toolbar with no visible label. Use an Input with aria-label.
### Mistakes to avoid

- Avoid `<label htmlFor="email">Email</label><Input id="email" />`. Instead: `<Field label="Email"><Input /></Field>`
- Avoid `{error && <p className="text-red-500">{error}</p>} under an input`. Instead: `<Field label="Email" error={error}>`
- Avoid `Setting aria-invalid or aria-describedby by hand`. Instead: `Field sets them from the error and description props`
- Avoid `Placeholder text instead of a label`. Instead: `A label prop, plus a placeholder only for an example value`
---
# Input

## Import

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

## Example

```tsx
<Field label="Email" error={errors.email}>
  <Input type="email" placeholder="you@example.com" />
</Field>
```

Sizes: `sm`, `default`, `lg`. All native input props work (`type`, `name`, `value`, `onChange`, `placeholder`, `disabled`).

An input without a visible label, like a toolbar search box, needs an `aria-label`:

```tsx
<Input type="search" aria-label="Search projects" placeholder="Search" />
```
### When not to use

- Text that can be several lines long. Use textarea.
- Picking one option from a known list. Use select.
- A yes or no choice. Use checkbox.
### Mistakes to avoid

- Avoid `<input className=...> (a raw input element)`. Instead: `<Input>`
- Avoid `<Input> without a Field or aria-label`. Instead: `<Field label="Email"><Input type="email" /></Field>`
- Avoid `<Input className="border-red-500"> to show an error`. Instead: `<Field label="Email" error="Enter a valid email">`
---
# Layout

Four primitives handle all layout spacing. They only accept steps from the spacing scale, so pages stay consistent.

| Component   | Direction  | Default gap | Use for                          |
| ----------- | ---------- | ----------- | -------------------------------- |
| `Stack`     | vertical   | 4           | sections, forms, lists           |
| `Inline`    | horizontal | 2           | button rows, tags, toolbars      |
| `Grid`      | columns    | 4           | card grids, multi-column layouts |
| `Container` | none       | none        | page width and side padding      |

Spacing scale: `1 | 2 | 3 | 4 | 6 | 8 | 12` (4 = 1rem).

## Import

```tsx
import { Stack, Inline, Grid, Container } from "@/components/ui/layout"
```

## Page layout

```tsx
<Container size="md">
  <Stack gap={8}>
    <Stack gap={2}>
      <h1 className="font-heading text-3xl font-bold">Settings</h1>
      <p className="text-muted-foreground">Manage your account.</p>
    </Stack>
    <Grid columns={{ base: 1, md: 2 }} gap={6}>
      <Card>...</Card>
      <Card>...</Card>
    </Grid>
    <Inline gap={2} justify="end">
      <Button variant="outline">Cancel</Button>
      <Button>Save</Button>
    </Inline>
  </Stack>
</Container>
```

## Semantic elements

Use `asChild` to render a different element:

```tsx
<Stack asChild gap={2}>
  <ul>
    <li>One</li>
    <li>Two</li>
  </ul>
</Stack>
```

## Props

- `Stack`: `gap`, `align` (`start | center | end | stretch | baseline`), `justify` (`start | center | end | between`), `asChild`
- `Inline`: same as Stack, plus `wrap` (default `true`). `align` defaults to `center`.
- `Grid`: `columns` (`1 | 2 | 3 | 4 | 6 | 12`, or `{ base, sm, md, lg, xl }`), `gap`, `asChild`
- `Container`: `size` (`sm | md | lg | xl | full`, default `lg`), `asChild`
### When not to use

- You need space inside an element, like padding in a card. Use card.
- You are laying out a data table. Use table.
### Mistakes to avoid

- Avoid `<div className="flex flex-col gap-4">`. Instead: `<Stack gap={4}>`
- Avoid `<div className="space-y-6">`. Instead: `<Stack gap={6}>`
- Avoid `<div className="flex items-center gap-2">`. Instead: `<Inline gap={2}>`
- Avoid `<div className="grid grid-cols-1 md:grid-cols-3 gap-6">`. Instead: `<Grid columns={{ base: 1, md: 3 }} gap={6}>`
- Avoid `<div className="mx-auto max-w-6xl px-4">`. Instead: `<Container>`
- Avoid `gap={5} or gap={10}`. Instead: `Use a step from the scale: 1, 2, 3, 4, 6, 8, 12.`
---
# Popover

## Import

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

## Example

```tsx
<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline">Share</Button>
  </PopoverTrigger>
  <PopoverContent align="end">
    <Stack gap={3}>
      <Field label="Link">
        <Input readOnly value={url} />
      </Field>
      <Button size="sm" onClick={copy}>
        Copy link
      </Button>
    </Stack>
  </PopoverContent>
</Popover>
```

`PopoverContent` takes `side` (`top | right | bottom | left`) and `align` (`start | center | end`).
### When not to use

- Only a short text hint. Use tooltip.
- A task that needs the user's full attention. Use dialog.
- Picking one option from a list. Use select.
### Mistakes to avoid

- Avoid `An absolutely positioned div toggled with useState`. Instead: `<Popover> handles position, focus and closing`
- Avoid `Interactive content in a Tooltip`. Instead: `<Popover>`
---
# Select

Built on Radix. Use `value` and `onValueChange` (or `defaultValue`). Item values must be non-empty strings.

## Import

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

## Example

```tsx
<Field label="Role">
  <Select value={role} onValueChange={setRole}>
    <SelectTrigger>
      <SelectValue placeholder="Pick a role" />
    </SelectTrigger>
    <SelectContent>
      <SelectItem value="admin">Admin</SelectItem>
      <SelectItem value="member">Member</SelectItem>
      <SelectItem value="viewer">Viewer</SelectItem>
    </SelectContent>
  </Select>
</Field>
```

## Groups

```tsx
<SelectContent>
  <SelectGroup>
    <SelectLabel>Fruits</SelectLabel>
    <SelectItem value="apple">Apple</SelectItem>
  </SelectGroup>
  <SelectSeparator />
  <SelectGroup>
    <SelectLabel>Vegetables</SelectLabel>
    <SelectItem value="carrot">Carrot</SelectItem>
  </SelectGroup>
</SelectContent>
```

Pass `name` to `Select` to include the value in a native form submit.
### When not to use

- Picking several options. Use checkbox.
- The list has only 2 or 3 options that should all be visible. Use checkbox.
- Showing a menu of actions. Use popover.
### Mistakes to avoid

- Avoid `<select><option>...</option></select> (a raw select element)`. Instead: `<Select> with SelectTrigger, SelectValue, SelectContent and SelectItem`
- Avoid `onChange={(e) => setValue(e.target.value)}`. Instead: `onValueChange={setValue}`
- Avoid `<SelectItem value="">None</SelectItem>`. Instead: `Leave the Select empty and use the SelectValue placeholder`
---
# Sheet

Same API as Dialog, plus `side`. The title is a prop on `SheetContent`.

## Import

```tsx
import { Sheet, SheetClose, SheetContent, SheetFooter, SheetTrigger } from "@/components/ui/sheet"
```

## Example

```tsx
<Sheet>
  <SheetTrigger asChild>
    <Button variant="outline">Filters</Button>
  </SheetTrigger>
  <SheetContent side="right" title="Filters" description="Narrow down the list.">
    <Stack gap={4}>
      <Field label="Status">
        <Select defaultValue="open">...</Select>
      </Field>
    </Stack>
    <SheetFooter>
      <SheetClose asChild>
        <Button>Apply</Button>
      </SheetClose>
    </SheetFooter>
  </SheetContent>
</Sheet>
```

`side`: `right` (default), `left`, `top`, `bottom`.
### When not to use

- A short focused task in the middle of the screen. Use dialog.
- Confirming a destructive action. Use alert-dialog.
- A few controls next to a button. Use popover.
### Mistakes to avoid

- Avoid `<SheetHeader><SheetTitle>...</SheetTitle></SheetHeader> (shadcn style)`. Instead: `<SheetContent title="...">`
- Avoid `A fixed-position div with a slide animation`. Instead: `<Sheet> handles focus, Escape and scroll lock`
---
# Table

Plain HTML table parts with BlankUI styles. For sorting and filtering, use a library like TanStack Table and render with these parts.

## Import

```tsx
import {
  Table,
  TableBody,
  TableCaption,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from "@/components/ui/table"
```

## Example

```tsx
<Table>
  <TableCaption>Team members</TableCaption>
  <TableHeader>
    <TableRow>
      <TableHead>Name</TableHead>
      <TableHead>Role</TableHead>
      <TableHead className="text-right">Actions</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    {members.map((m) => (
      <TableRow key={m.id}>
        <TableCell className="font-medium">{m.name}</TableCell>
        <TableCell>{m.role}</TableCell>
        <TableCell className="text-right">
          <Button size="sm" variant="ghost">
            Edit
          </Button>
        </TableCell>
      </TableRow>
    ))}
  </TableBody>
</Table>
```
### When not to use

- Laying out a page in columns. Use layout.
- A few items with different content each. Use card.
### Mistakes to avoid

- Avoid `A grid of divs that looks like a table`. Instead: `<Table> so screen readers can read rows and columns`
- Avoid `<table className=...> (a raw table element)`. Instead: `<Table>`
- Avoid `TableHead cells inside TableBody`. Instead: `TableHead in TableHeader, TableCell in TableBody`
---
# Tabs

Built on Radix. Arrow keys move between tabs. Use `defaultValue`, or `value` with `onValueChange` to control it.

## Import

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

## Example

```tsx
<Tabs defaultValue="account">
  <TabsList>
    <TabsTrigger value="account">Account</TabsTrigger>
    <TabsTrigger value="password">Password</TabsTrigger>
  </TabsList>
  <TabsContent value="account">
    <Card>...</Card>
  </TabsContent>
  <TabsContent value="password">
    <Card>...</Card>
  </TabsContent>
</Tabs>
```
### When not to use

- Moving between pages with their own URL. Use links in your navigation.
- Steps the user must go through in order. Use a step-by-step form with Buttons.
- Picking a value for a form. Use select.
### Mistakes to avoid

- Avoid `Buttons that set state and show different divs`. Instead: `<Tabs> handles keyboard navigation and ARIA roles`
- Avoid `A TabsTrigger without a TabsContent of the same value`. Instead: `One TabsContent per TabsTrigger`
---
# Textarea

## Import

```tsx
import { Textarea } from "@/components/ui/textarea"
```

## Example

```tsx
<Field label="Message" description="Up to 500 characters.">
  <Textarea rows={5} maxLength={500} />
</Field>
```
### When not to use

- A single line of text. Use input.
### Mistakes to avoid

- Avoid `<textarea className=...> (a raw textarea element)`. Instead: `<Textarea>`
---
# Toast

Built on [sonner](https://sonner.emilkowal.ski). Render one `<Toaster />` in the root layout, then call `toast()` anywhere, including outside React components.

## Import

```tsx
import { Toaster, toast } from "@/components/ui/toast"
```

## Setup

```tsx
// app/layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" data-theme="default" data-mode="light">
      <body>
        {children}
        <Toaster />
      </body>
    </html>
  )
}
```

## Examples

```tsx
toast("Link copied")
toast.success("Project created", { description: "Invite your team next." })
toast.error("Could not save changes", { action: { label: "Retry", onClick: save } })
toast("Message archived", { action: { label: "Undo", onClick: unarchive } })
```

Promise toasts:

```tsx
toast.promise(saveProject(), {
  loading: "Saving...",
  success: "Saved",
  error: "Could not save",
})
```
### When not to use

- Asking the user to confirm before an action. Use alert-dialog.
- A validation error on a form field. Use field (use the error prop).
- Information the user must read or act on. Use dialog.
### Mistakes to avoid

- Avoid `import { toast } from "sonner" in app code`. Instead: `import { toast } from "@/components/ui/toast"`
- Avoid `useToast() hook (old shadcn toast)`. Instead: `toast() from @/components/ui/toast`
- Avoid `Several <Toaster /> elements`. Instead: `One <Toaster /> in the root layout`
- Avoid `alert('Saved')`. Instead: `toast.success("Saved")`
---
# Tooltip

No `TooltipProvider` is needed. The trigger must be focusable, so use `asChild` with a Button.

## Import

```tsx
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"
```

## Example

```tsx
import { Copy } from "lucide-react"

;<Tooltip>
  <TooltipTrigger asChild>
    <Button size="icon" variant="ghost" aria-label="Copy">
      <Copy />
    </Button>
  </TooltipTrigger>
  <TooltipContent>Copy to clipboard</TooltipContent>
</Tooltip>
```
### When not to use

- The content has links, buttons or inputs. Use popover.
- The information is needed to complete a task. Use field (put it in the description).
- Long explanations. Use popover.
### Mistakes to avoid

- Avoid `<TooltipProvider> around the app`. Instead: `Nothing. Each Tooltip has its own provider.`
- Avoid `title="..." attributes for hints`. Instead: `<Tooltip>`
- Avoid `A Tooltip as the only label of an icon button`. Instead: `Give the Button an aria-label as well`