/shadcn-ui

name: shadcn-ui
description: shadcn/ui component patterns with Radix primitives and Tailwind styling. Use when building UI components, using CVA variants, implementing compound components, or styling with data-slot attributes. Triggers on shadcn, cva, cn(), data-slot, Radix, Button, Card, Dialog, VariantProps.

shadcn/ui Component Development

Contents

• [CLI Commands](#cli-commands) - Installing and adding components
• [Quick Reference](#quick-reference) - cn(), basic CVA pattern
• [Component Anatomy](#component-anatomy) - Props typing, asChild, data-slot
• [Component Patterns](#component-patterns) - Compound components
• [Styling Techniques](#styling-techniques) - CVA variants, modern CSS selectors, accessibility states
• [Decision Tables](#decision-tables) - When to use CVA, compound components, asChild, Context
• [Common Patterns](#common-patterns) - Form elements, dialogs, sidebars
• [Reference Files](#reference-files) - Full implementations and advanced patterns

CLI Commands

Initialize shadcn/ui

npx shadcn@latest init

This creates a `components.json` configuration file and sets up:

• Tailwind CSS configuration
• CSS variables for theming
• cn() utility function
• Required dependencies

Add Components

# Add a single component
npx shadcn@latest add button

# Add multiple components
npx shadcn@latest add button card dialog

# Add all available components
npx shadcn@latest add --all

**Important:** The package name changed in 2024:

• Old (deprecated): `npx shadcn-ui@latest add`
• Current: `npx shadcn@latest add`

Common Options

• `-y, --yes` - Skip confirmation prompt
• `-o, --overwrite` - Overwrite existing files
• `-c, --cwd <cwd>` - Set working directory
• `--src-dir` - Use src directory structure

Gates (CLI and file changes)

Run these **in order** before `init` / `add` (skip only when you are not running the CLI—e.g. copying snippets from this skill):

1. **Working directory:** **Pass:** `pwd` and `package.json` at that path identify the app root that should receive `components/` and `components.json` (use `-c <cwd>` if the shell is elsewhere). 2. **After `init`:** **Pass:** `components.json` exists at that app root (or the documented path for your monorepo layout). 3. **Before `--overwrite`:** **Pass:** you can list which tracked files will be replaced, or version control shows the change is intentional and recoverable.

Quick Reference

cn() Utility

import { clsx, type ClassValue } from "clsx"
import { twMerge } from "tailwind-merge"

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

Basic CVA Pattern

import { cva, type VariantProps } from "class-variance-authority"

const buttonVariants = cva(
  "base-classes-applied-to-all-variants",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground",
        outline: "border bg-background",
      },
      size: {
        sm: "h-8 px-3",
        lg: "h-10 px-6",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "sm",
    },
  }
)

function Button({
  variant,
  size,
  className,
  ...props
}: React.ComponentProps<"button"> & VariantProps<typeof buttonVariants>) {
  return (
    <button
      className={cn(buttonVariants({ variant, size }), className)}
      {...props}
    />
  )
}

export { Button, buttonVariants }

Component Anatomy

Props Typing Patterns

// HTML elements
function Component({ className, ...props }: React.ComponentProps<"div">) {
  return <div className={cn("base-classes", className)} {...props} />
}

// Radix primitives
function Component({ className, ...props }: React.ComponentProps<typeof RadixPrimitive.Root>) {
  return <RadixPrimitive.Root className={cn("base-classes", className)} {...props} />
}

// With CVA variants
function Component({
  variant, size, className, ...props
}: React.ComponentProps<"button"> & VariantProps<typeof variants>) {
  return <button className={cn(variants({ variant, size }), className)} {...props} />
}

asChild Pattern

Enables polymorphic rendering via `@radix-ui/react-slot`:

import { Slot } from "@radix-ui/react-slot"

function Button({
  asChild = false,
  className,
  variant,
  size,
  ...props
}: React.ComponentProps<"button"> & VariantProps<typeof buttonVariants> & { asChild?: boolean }) {
  const Comp = asChild ? Slot : "button"
  return (
    <Comp
      data-slot="button"
      className={cn(buttonVariants({ variant, size }), className)}
      {...props}
    />
  )
}

**Usage:**

<Button>Click me</Button>                           // Renders <button>
<Button asChild><a href="/home">Home</a></Button>   // Renders <a> with button styling
<Button asChild><Link href="/dash">Dash</Link></Button>  // Works with Next.js Link

data-slot Attributes

Every component includes `data-slot` for CSS targeting:

function Card({ ...props }) { return <div data-slot="card" {...props} /> }
function CardHeader({ ...props }) { return <div data-slot="card-header" {...props} /> }

**CSS/Tailwind targeting:**

[data-slot="button"] { /* styles */ }
[data-slot="card"] [data-slot="button"] { /* nested targeting */ }

<div className="[&_[data-slot=button]]:shadow-lg">
  <Button>Automatically styled</Button>
</div>

**Conditional layouts with has():**

<div
  data-slot="card-header"
  className={cn(
    "grid gap-2",
    "has-data-[slot=card-action]:grid-cols-[1fr_auto]"
  )}
/>

Component Patterns

Compound Components

export { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter }

function Card({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="card"
      className={cn("bg-card text-card-foreground flex flex-col gap-6 rounded-xl border py-6 shadow-sm", className)}
      {...props}
    />
  )
}

function CardHeader({ className, ...props }: React.ComponentPro