shadcn/ui

When to Use

shadcn/ui is the default component and styling approach for all frontend projects. Always prefer shadcn/ui components (<Button> , <Input> , <Card> , etc.) over raw HTML elements or hand-styled Tailwind.

Use this skill for:

• Component installation, composition, and customization

• Theming with CSS variables (OKLCH color space)

• Form integration with react-hook-form + zod

• Accessible UI patterns (via Radix UI primitives)

Only skip shadcn/ui when a project explicitly uses a different component system (e.g., MUI, Chakra).

Installation and Setup

Initialize in a Next.js Project

npx shadcn@latest init

This creates:

• components.json — configuration file (style is always "new-york" , the only supported style)

• lib/utils.ts — the cn() utility (clsx + tailwind-merge)

• components/ui/ — raw shadcn/ui components (avoid heavy modifications)

• Recommended additional directories: components/primitives/ (lightly customized wrappers), components/blocks/ (product-level compositions)

Key components.json fields:

• tailwind.config : Leave blank for Tailwind v4 projects

• tailwind.cssVariables : true (default, uses OKLCH color space)

• registries : Optional array for custom component registries

CLI Commands

npx shadcn@latest init # Initialize project npx shadcn@latest add button # Add component(s) npx shadcn@latest add --all # Add all components npx shadcn@latest list # List available components npx shadcn@latest diff button # Show changes vs registry npx shadcn@latest build # Build registry for publishing npx shadcn@latest migrate radix # Migrate to unified radix-ui package

Use --rtl flag with init for right-to-left layout support.

Components are copied into your codebase (not installed as dependencies). You own the code and can modify it.

Ecosystem Notes

• Tailwind v4: CSS-first configuration via @theme directive in globals.css . No tailwind.config.js needed. Tailwind v3 projects are still supported.

• tw-animate-css: Replaces deprecated tailwindcss-animate . Install with npm install tw-animate-css and import in globals.css : @import "tw-animate-css";

• Unified Radix package: The radix-ui package replaces individual @radix-ui/react-* packages. Migrate with npx shadcn@latest migrate radix .

• React 19: forwardRef is no longer needed. Components accept ref as a regular prop. Both patterns work in existing codebases.

• "new-york" only: The old "default" style is deprecated. All new projects use "new-york".

The cn() Utility

Always use cn() for conditional/merged class names:

import { cn } from "@/lib/utils";

<div className={cn( "flex items-center gap-2", isActive && "bg-primary text-primary-foreground", className, // always forward className prop )} />;

Component Usage Patterns

Dialog

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

function DeleteDialog({ onConfirm }: { onConfirm: () => void }) { const [open, setOpen] = useState(false);

return ( <Dialog open={open} onOpenChange={setOpen}> <DialogTrigger asChild> <Button variant="destructive">Delete</Button> </DialogTrigger> <DialogContent> <DialogHeader> <DialogTitle>Are you sure?</DialogTitle> <DialogDescription>This action cannot be undone.</DialogDescription> </DialogHeader> <DialogFooter> <Button variant="outline" onClick={() => setOpen(false)}> Cancel </Button> <Button variant="destructive" onClick={() => { onConfirm(); setOpen(false); }} > Delete </Button> </DialogFooter> </DialogContent> </Dialog> ); }

Sheet (Side Panel)

import { Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle, SheetTrigger, } from "@/components/ui/sheet";

<Sheet> <SheetTrigger asChild> <Button variant="outline">Open Settings</Button> </SheetTrigger> <SheetContent side="right" className="w-[400px]"> <SheetHeader> <SheetTitle>Settings</SheetTitle> <SheetDescription>Configure your preferences.</SheetDescription> </SheetHeader> {/* Content here */} </SheetContent> </Sheet>;

Command (Command Palette / Combobox)

import { Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, } from "@/components/ui/command";

function CommandMenu() { const [open, setOpen] = useState(false);

useEffect(() => { const down = (e: KeyboardEvent) => { if (e.key === "k" && (e.metaKey || e.ctrlKey)) { e.preventDefault(); setOpen((open) => !open); } }; document.addEventListener("keydown", down); return () => document.removeEventListener("keydown", down); }, []);

return ( <CommandDialog open={open} onOpenChange={setOpen}> <CommandInput placeholder="Type a command or search..." /> <CommandList> <CommandEmpty>No results found.</CommandEmpty> <CommandGroup heading="Actions"> <CommandItem onSelect={() => {}}> <span>New Document</span> </CommandItem> </CommandGroup> </CommandList> </CommandDialog> ); }

DataTable (with TanStack Table)

import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow, } from "@/components/ui/table"; import { ColumnDef, flexRender, getCoreRowModel, useReactTable, } from "@tanstack/react-table";

// Add getSortedRowModel, getFilteredRowModel, getPaginationRowModel as needed

function DataTable<TData, TValue>({ columns, data, }: { columns: ColumnDef<TData, TValue>[]; data: TData[]; }) { const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel(), });

return ( <Table> <TableHeader> {table.getHeaderGroups().map((headerGroup) => ( <TableRow key={headerGroup.id}> {headerGroup.headers.map((header) => ( <TableHead key={header.id}> {header.isPlaceholder ? null : flexRender( header.column.columnDef.header, header.getContext(), )} </TableHead> ))} </TableRow> ))} </TableHeader> <TableBody> {table.getRowModel().rows.map((row) => ( <TableRow key={row.id}> {row.getVisibleCells().map((cell) => ( <TableCell key={cell.id}> {flexRender(cell.column.columnDef.cell, cell.getContext())} </TableCell> ))} </TableRow> ))} </TableBody> </Table> ); }

Other Notable Components

These are available via npx shadcn@latest add <name> (see official docs for usage):

• Sidebar — app-level navigation with collapsible groups

• Chart — chart components built on Recharts

• Drawer — mobile-friendly bottom sheet (Vaul-based)

• Carousel — content carousel (Embla-based)

• Resizable — resizable panel layouts

• Field, Input Group, Button Group — form layout helpers

• Spinner — loading spinner component

• Kbd — keyboard shortcut display

• Empty — empty state component

Composition Patterns

Controlled vs Uncontrolled

Most shadcn/ui components support both patterns:

// Uncontrolled — component manages its own state <Dialog> <DialogTrigger>Open</DialogTrigger> <DialogContent>...</DialogContent> </Dialog>

// Controlled — you manage the state const [open, setOpen] = useState(false) <Dialog open={open} onOpenChange={setOpen}> <DialogContent>...</DialogContent> </Dialog>

Use controlled when you need to:

• Close on form submit

• Open programmatically (e.g., after an action)

• Prevent closing under certain conditions

The asChild Pattern

Use asChild to render a different element while keeping the trigger behavior:

// Renders a <button> wrapping an <a> — BAD <DialogTrigger> <Link href="/settings">Settings</Link> </DialogTrigger>

// Renders just the <a> with trigger behavior — GOOD <DialogTrigger asChild> <Link href="/settings">Settings</Link> </DialogTrigger>

Forwarding className

Always forward className in custom components built on shadcn/ui:

interface CustomCardProps extends React.ComponentProps<typeof Card> { title: string; }

function CustomCard({ title, className, ...props }: CustomCardProps) { return ( <Card className={cn("p-6", className)} {...props}> <CardTitle>{title}</CardTitle> </Card> ); }

With React 19, ref is a regular prop — no forwardRef wrapper needed. React.ComponentProps<typeof Card> already includes ref in React 19.

Styling and Theming

CSS Variables

shadcn/ui uses CSS variables for theming, defined in globals.css . New projects use OKLCH color space. In Tailwind v4 projects, theme tokens are registered with @theme inline instead of tailwind.config.js . Existing HSL-based projects continue to work.

:root { --background: oklch(1 0 0); --foreground: oklch(0.141 0.005 285.823); --primary: oklch(0.21 0.006 285.885); --primary-foreground: oklch(0.985 0.002 247.858); --secondary: oklch(0.967 0.001 286.375); --secondary-foreground: oklch(0.21 0.006 285.885); --muted: oklch(0.967 0.001 286.375); --muted-foreground: oklch(0.552 0.016 285.938); --destructive: oklch(0.577 0.245 27.325); --border: oklch(0.92 0.004 286.32); --input: oklch(0.92 0.004 286.32); --ring: oklch(0.705 0.015 286.067); --radius: 0.625rem; }

.dark { --background: oklch(0.141 0.005 285.823); --foreground: oklch(0.985 0.002 247.858); /* ... dark mode values */ }

Extending with Tailwind

Use Tailwind utilities to customize components. The cn() function handles merge conflicts:

<Button className="w-full justify-start text-left font-normal"> Select a date </Button>

Dark Mode

shadcn/ui supports dark mode via the dark class on <html> . Use next-themes :

import { ThemeProvider } from "next-themes";

// In layout.tsx <ThemeProvider attribute="class" defaultTheme="system" enableSystem> {children} </ThemeProvider>;

Toggle:

import { useTheme } from "next-themes";

function ThemeToggle() { const { setTheme, theme } = useTheme(); return ( <Button variant="ghost" size="icon" onClick={() => setTheme(theme === "dark" ? "light" : "dark")} > <Sun className="h-5 w-5 rotate-0 scale-100 dark:-rotate-90 dark:scale-0" /> <Moon className="absolute h-5 w-5 rotate-90 scale-0 dark:rotate-0 dark:scale-100" /> </Button> ); }

Form Integration (react-hook-form + zod)

Schema Definition

import { z } from "zod";

const formSchema = z.object({ name: z.string().min(2, "Name must be at least 2 characters"), email: z.string().email("Invalid email address"), role: z.enum(["admin", "user", "viewer"]), notifications: z.boolean().default(false), });

type FormValues = z.infer<typeof formSchema>;

Form Component

import { useForm } from "react-hook-form"; import { zodResolver } from "@hookform/resolvers/zod"; import { Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, } from "@/components/ui/form";

function UserForm() { const form = useForm<FormValues>({ resolver: zodResolver(formSchema), defaultValues: { name: "", email: "", role: "user", notifications: false, }, });

function onSubmit(values: FormValues) { // values is fully typed and validated console.log(values); }

return ( <Form {...form}> <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-6"> <FormField control={form.control} name="name" render={({ field }) => ( <FormItem> <FormLabel>Name</FormLabel> <FormControl> <Input placeholder="John Doe" {...field} /> </FormControl> <FormDescription>Your display name.</FormDescription> <FormMessage /> </FormItem> )} />

    <FormField
      control={form.control}
      name="email"
      render={({ field }) => (
        <FormItem>
          <FormLabel>Email</FormLabel>
          <FormControl>
            <Input type="email" {...field} />
          </FormControl>
          <FormMessage />
        </FormItem>
      )}
    />

    <FormField
      control={form.control}
      name="role"
      render={({ field }) => (
        <FormItem>
          <FormLabel>Role</FormLabel>
          <Select onValueChange={field.onChange} defaultValue={field.value}>
            <FormControl>
              <SelectTrigger>
                <SelectValue placeholder="Select a role" />
              </SelectTrigger>
            </FormControl>
            <SelectContent>
              <SelectItem value="admin">Admin</SelectItem>
              <SelectItem value="user">User</SelectItem>
              <SelectItem value="viewer">Viewer</SelectItem>
            </SelectContent>
          </Select>
          <FormMessage />
        </FormItem>
      )}
    />

    <Button type="submit">Save</Button>
  </form>
</Form>

); }

Accessibility

Built-in Defaults

shadcn/ui components (via Radix UI) include:

• Keyboard navigation (Tab, Enter, Escape, Arrow keys)

• Focus management (focus trap in dialogs, return focus on close)

• ARIA attributes (role, aria-expanded, aria-controls, etc.)

• Screen reader announcements

Required Additions

You must still provide:

// 1. Always include DialogDescription (or visually hide it) <DialogHeader> <DialogTitle>Edit Profile</DialogTitle> <DialogDescription>Make changes to your profile here.</DialogDescription> </DialogHeader>

// If no visible description, use VisuallyHidden: <DialogDescription className="sr-only"> Dialog for editing profile settings </DialogDescription>

// 2. Label form inputs <FormField name="email" render={({ field }) => ( <FormItem> <FormLabel>Email</FormLabel> {/* Required for accessibility */} <FormControl> <Input {...field} /> </FormControl> </FormItem> )} />

// 3. Add aria-label for icon-only buttons <Button variant="ghost" size="icon" aria-label="Close menu"> <X className="h-4 w-4" /> </Button>

// 4. data-testid for testing <Button data-testid="submit-form">Submit</Button>

Common UI Patterns

Loading States

import { Loader2 } from "lucide-react";

<Button disabled={isLoading}> {isLoading && <Loader2 className="mr-2 h-4 w-4 animate-spin" />} {isLoading ? "Saving..." : "Save Changes"} </Button>;

// Skeleton for content loading import { Skeleton } from "@/components/ui/skeleton";

<Card> <CardHeader> <Skeleton className="h-6 w-[200px]" /> <Skeleton className="h-4 w-[300px]" /> </CardHeader> <CardContent> <Skeleton className="h-20 w-full" /> </CardContent> </Card>;

Empty States

Use the <Empty> component from shadcn/ui, or build a simple one:

<div className="flex flex-col items-center justify-center py-12 text-center"> <InboxIcon className="h-12 w-12 text-muted-foreground" /> <h3 className="mt-4 text-lg font-semibold">No results</h3> <p className="mt-2 text-sm text-muted-foreground"> Get started by creating your first item. </p> <Button className="mt-4">Create New</Button> </div>

Error Display

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

function ErrorAlert({ message }: { message: string }) { return ( <Alert variant="destructive"> <AlertCircle className="h-4 w-4" /> <AlertTitle>Error</AlertTitle> <AlertDescription>{message}</AlertDescription> </Alert> ); }

Toast Notifications (Sonner)

The old useToast hook is deprecated. Use sonner instead:

npx shadcn@latest add sonner

Add <Toaster /> once in your root layout:

import { Toaster } from "@/components/ui/sonner";

export default function RootLayout({ children, }: { children: React.ReactNode; }) { return ( <html> <body> {children} <Toaster /> </body> </html> ); }

import { toast } from "sonner";

function SaveButton() { async function handleSave() { try { await save(); toast.success("Your changes have been saved."); } catch { toast.error("Failed to save changes."); } }

return <Button onClick={handleSave}>Save</Button>; }

Anti-Patterns

1. Raw HTML Instead of Components

// BAD <button className="bg-blue-500 text-white px-4 py-2 rounded">Click</button>

// GOOD <Button>Click</Button>

2. Not Using asChild for Custom Triggers

// BAD — nested interactive elements <DialogTrigger><button>Open</button></DialogTrigger>

// GOOD <DialogTrigger asChild><Button>Open</Button></DialogTrigger>

3. Hardcoding Colors Instead of CSS Variables

// BAD <div className="bg-gray-100 text-gray-900 dark:bg-gray-800 dark:text-white">

// GOOD — uses theme variables, dark mode automatic <div className="bg-background text-foreground">

Never hardcode oklch(...) values either — always use semantic class names like bg-primary , text-muted-foreground .

4. Missing Form Validation Feedback

// BAD — no error message shown <FormField name="email" render={({ field }) => ( <FormItem> <Input {...field} /> </FormItem> )} />

// GOOD — shows validation errors <FormField name="email" render={({ field }) => ( <FormItem> <FormLabel>Email</FormLabel> <FormControl><Input {...field} /></FormControl> <FormMessage /> {/* Shows zod validation errors */} </FormItem> )} />

5. Not Forwarding Props

// BAD — className, onClick, etc. are lost function MyButton({ label }: { label: string }) { return <Button>{label}</Button>; }

// GOOD — all button props forwarded function MyButton({ label, ...props }: { label: string } & React.ComponentProps<typeof Button>) { return <Button {...props}>{label}</Button>; }

6. Using Deprecated useToast

// DEPRECATED — do not use import { useToast } from "@/hooks/use-toast"; const { toast } = useToast();

// CORRECT — use sonner import { toast } from "sonner"; toast.success("Saved");