shadcn-ui/ui/shadcn

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.

Current Project Context

!`npx shadcn@latest info --json`

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

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

• 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

• 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
• 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

• 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 follows the project base. Use toast from the toast component for

Base UI projects. Use toast() from sonner for Radix and React Aria projects.

• 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

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

Chat & Messaging → chat.md

• Chat UI composes the chat primitives. Conversations use MessageScroller, rows use Message, surfaces use Bubble. Never hand-rolled bubble divs or a raw scroll container.
• `MessageScroller` owns scroll behavior. Streaming follow, anchoring, and jump-to-latest (MessageScrollerButton) are built in. Don't write a useStickToBottom/ResizeObserver hook.
• Attachments use `Attachment`; system notes and dividers use `Marker`. Not Item cards or Separator + a label.
• Assistant activity uses `Trace`. Reasoning, tool calls, sources and steps are TraceLines in a Trace, one Trace per run of message parts. Behavior wraps the line: TraceCollapsible, a sheet trigger or a link. Not a hand-rolled Collapsible or a Marker.

CLI

• Never decode preset codes or build preset URLs manually. Use npx shadcn@latest preset decode <code>, preset url <code>, or preset open <code>. For project-aware preset detection, use npx shadcn@latest preset resolve.
• Apply preset codes directly with the CLI. Use npx shadcn@latest apply <code> for existing projects, or npx shadcn@latest init --preset <code> when initializing.

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>
</FieldGroup>
// Validation: data-invalid on Field, aria-invalid on the control.
<Field data-invalid>
  <FieldLabel>Email</FieldLabel>
  <Input aria-invalid />
  <FieldDescription>Invalid email.</FieldDescription>
</Field>
// Icons in buttons: data-icon, no sizing classes.
<Button>
  <SearchIcon data-icon="inline-start" />
  Search
</Button>
// Spacing: gap-*, not space-y-*.
<div className="flex flex-col gap-4">  // correct
<div className="space-y-4">           // wrong
// Equal dimensions: size-*, not w-* h-*.
<Avatar className="size-10">   // correct
<Avatar className="w-10 h-10"> // wrong
// Status colors: Badge variants or semantic tokens, not raw colors.
<Badge variant="secondary">+20.1%</Badge>    // correct
<span className="text-emerald-600">+20.1%</span> // wrong

Component Selection

Key Fields

The injected project context contains these key fields:

• `aliases` → use the actual alias prefix for imports (e.g. @/, ~/), never hardcode.
• `isRSC` → when true, components using useState, useEffect, event handlers, or browser APIs need "use client" at the top of the file. Always reference this field when advising on the directive.
• `tailwindVersion` → "v4" uses @theme inline blocks; "v3" uses tailwind.config.js.
• `tailwindCssFile` → the global CSS file where custom CSS variables are defined. Always edit this file, never create a new one.
• `style` → component visual treatment (e.g. nova, vega).
• `base` → primitive library (radix or base). Affects component APIs and available props.
• `iconLibrary` → determines icon imports. Use lucide-react for lucide, @tabler/icons-react for tabler, etc. Never assume lucide-react.
• `resolvedPaths` → exact file-system destinations for components, utils, hooks, etc.
• `framework` → routing and file conventions (e.g. Next.js App Router vs Vite SPA).
• `packageManager` → use this for any non-shadcn dependency installs (e.g. pnpm add date-fns vs npm install date-fns).
• `preset` → resolved preset code and values for the current project. Use npx shadcn@latest preset resolve --json when you only need preset information.

See cli.md — `info` command for the full field reference.

Component Docs, Examples, and Usage

Run npx shadcn@latest docs <component> to get the URLs for a component's documentation, examples, and API reference. Fetch these URLs to get the actual content.

npx shadcn@latest docs button dialog select

When creating, fixing, debugging, or using a component, always run `npx shadcn@latest docs` and fetch the URLs first. This ensures you're working with the correct API and usage patterns rather than guessing.

Workflow