/shadcn

name: shadcn
type: reference
description: "Provides shadcn/ui component integration patterns, theming, and design system composition for React projects. Use when working with shadcn/ui or when the user mentions shadcn, shadcn/ui, or building a component library."
when_to_use: "When using shadcn/ui components, configuring component libraries, or building design systems with Radix and Tailwind"
allowed-tools: Read, Glob, Grep, Write, Edit, Bash
user-invocable: false
paths: ["**/*.tsx", "**/*.jsx", "**/components.json"]
effort: 3

shadcn/ui

A framework for building ui, components and design systems. Components are added as source code to the user's project via the CLI.

> **IMPORTANT:** Run all CLI commands using the project's package runner: `npx shadcn@latest`, `pnpm dlx shadcn@latest`, or `bunx --bun shadcn@latest` — based on the project's `packageManager`. Examples below use `npx shadcn@latest` but substitute the correct runner for the project.

When to Use

• Use when adding new components from shadcn/ui or community registries.
• Use when styling, composing, or debugging existing shadcn/ui components.
• Use when initializing a new project or switching design system presets.
• Use to retrieve component documentation, examples, and API references.

Current Project Context

!`npx shadcn@latest info --json 2>/dev/null || echo '{"error": "No shadcn project found. Run shadcn init first."}'`

The JSON above contains the project config and installed components. Use `npx shadcn@latest docs <component>` to get documentation and example URLs for any component.

Principles

1. **Use existing components first.** Use `npx shadcn@latest search` to check registries before writing custom UI. Check community registries too. 2. **Compose, don't reinvent.** Settings page = Tabs + Card + form controls. Dashboard = Sidebar + Card + Chart + Table. 3. **Use built-in variants before custom styles.** `variant="outline"`, `size="sm"`, etc. 4. **Use semantic colors.** `bg-primary`, `text-muted-foreground` — never raw values like `bg-blue-500`.

Critical Rules

These rules are **always enforced**. Each links to a file with Incorrect/Correct code pairs.

Styling & Tailwind → [styling.md](./rules/styling.md)

• **`className` for layout, not styling.** Never override component colors or typography.
• **No `space-x-*` or `space-y-*`.** Use `flex` with `gap-*`. For vertical stacks, `flex flex-col gap-*`.
• **Use `size-*` when width and height are equal.** `size-10` not `w-10 h-10`.
• **Use `truncate` shorthand.** Not `overflow-hidden text-ellipsis whitespace-nowrap`.
• **No manual `dark:` color overrides.** Use semantic tokens (`bg-background`, `text-muted-foreground`).
• **Use `cn()` for conditional classes.** Don't write manual template literal ternaries.
• **No manual `z-index` on overlay components.** Dialog, Sheet, Popover, etc. handle their own stacking.

Forms & Inputs → [forms.md](./rules/forms.md)

• **Forms use `FieldGroup` + `Field`.** Never use raw `div` with `space-y-*` or `grid gap-*` for form layout.
• **`InputGroup` uses `InputGroupInput`/`InputGroupTextarea`.** Never raw `Input`/`Textarea` inside `InputGroup`.
• **Buttons inside inputs use `InputGroup` + `InputGroupAddon`.**
• **Option sets (2–7 choices) use `ToggleGroup`.** Don't loop `Button` with manual active state.
• **`FieldSet` + `FieldLegend` for grouping related checkboxes/radios.** Don't use a `div` with a heading.
• **Field validation uses `data-invalid` + `aria-invalid`.** `data-invalid` on `Field`, `aria-invalid` on the control. For disabled: `data-disabled` on `Field`, `disabled` on the control.

Component Structure → [composition.md](./rules/composition.md)

• **Items always inside their Group.** `SelectItem` → `SelectGroup`. `DropdownMenuItem` → `DropdownMenuGroup`. `CommandItem` → `CommandGroup`.
• **Use `asChild` (radix) or `render` (base) for custom triggers.** Check `base` field from `npx shadcn@latest info`. → [base-vs-radix.md](./rules/base-vs-radix.md)
• **Dialog, Sheet, and Drawer always need a Title.** `DialogTitle`, `SheetTitle`, `DrawerTitle` required for accessibility. Use `className="sr-only"` if visually hidden.
• **Use full Card composition.** `CardHeader`/`CardTitle`/`CardDescription`/`CardContent`/`CardFooter`. Don't dump everything in `CardContent`.
• **Button has no `isPending`/`isLoading`.** Compose with `Spinner` + `data-icon` + `disabled`.
• **`TabsTrigger` must be inside `TabsList`.** Never render triggers directly in `Tabs`.
• **`Avatar` always needs `AvatarFallback`.** For when the image fails to load.

Use Components, Not Custom Markup → [composition.md](./rules/composition.md)

• **Use existing components before custom markup.** Check if a component exists before writing a styled `div`.
• **Callouts use `Alert`.** Don't build custom styled divs.
• **Empty states use `Empty`.** Don't build custom empty state markup.
• **Toast via `sonner`.** Use `toast()` from `sonner`.
• **Use `Separator`** instead of `<hr>` or `<div className="border-t">`.
• **Use `Skeleton`** for loading placeholders. No custom `animate-pulse` divs.
• **Use `Badge`** instead of custom styled spans.

Icons → [icons.md](./rules/icons.md)

• **Icons in `Button` use `data-icon`.** `data-icon="inline-start"` or `data-icon="inline-end"` on the icon.
• **No sizing classes on icons inside components.** Components handle icon sizing via CSS. No `size-4` or `w-4 h-4`.
• **Pass icons as objects, not string keys.** `icon={CheckIcon}`, not a string lookup.

CLI

• **Never decode or fetch preset codes manually.** Pass them directly to `npx shadcn@latest init --preset <code>`.

Key Patterns

These are the most common patterns that differentiate correct shadcn/ui code. For edge cases, see the linked rule files above.

// Form layout: FieldGroup + Field, not div + Label.
<FieldGroup>
  <Field>
    <FieldLabel htmlFor="email">Email</FieldLabel>
    <Input id="email" />
  </Field>
</FieldGro