Shadcn UI

shadcn/ui Component Patterns

Expert guide for building accessible, customizable UI components with shadcn/ui.

Installation

OpenClaw / Moltbot / Clawbot

npx clawhub@latest install shadcn-ui

WHEN

• Setting up a new project with shadcn/ui
• Installing or configuring individual components
• Building forms with React Hook Form and Zod validation
• Creating accessible UI components (buttons, dialogs, dropdowns, sheets)
• Customizing component styling with Tailwind CSS
• Implementing design systems with shadcn/ui
• Building Next.js applications with TypeScript

What is shadcn/ui?

A collection of reusable components you copy into your project — not an npm package. You own the code. Built on Radix UI (accessibility) and Tailwind CSS (styling).

Quick Start

# New Next.js project
npx create-next-app@latest my-app --typescript --tailwind --eslint --app
cd my-app
npx shadcn@latest init

# Install components
npx shadcn@latest add button input form card dialog select toast
npx shadcn@latest add --all  # or install everything

Core Concepts

The cn Utility

Merges Tailwind classes with conflict resolution — used in every component:

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

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

Class Variance Authority (CVA)

Manages component variants — the pattern behind every shadcn/ui component:

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

const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
        outline: "border border-input bg-background hover:bg-accent",
        secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/90",
        ghost: "hover:bg-accent hover:text-accent-foreground",
        link: "text-primary underline-offset-4 hover:underline",
      },
      size: {
        default: "h-10 px-4 py-2",
        sm: "h-9 rounded-md px-3",
        lg: "h-11 rounded-md px-8",
        icon: "h-10 w-10",
      },
    },
    defaultVariants: { variant: "default", size: "default" },
  }
)

Essential Components

Button

import { Button } from "@/components/ui/button"
import { Loader2 } from "lucide-react"

// Variants: default | destructive | outline | secondary | ghost | link
// Sizes: default | sm | lg | icon
Click me

// Loading state

  
  Please wait


// As link (uses Radix Slot)

  Go to Dashboard

Forms with Validation

The standard pattern: Zod schema + React Hook Form + shadcn Form components.

npx shadcn@latest add form input select checkbox textarea

"use client"

import { zodResolver } from "@hookform/resolvers/zod"
import { useForm } from "react-hook-form"
import * as z from "zod"
import { Button } from "@/components/ui/button"
import {
  Form, FormControl, FormDescription,
  FormField, FormItem, FormLabel, FormMessage,
} from "@/components/ui/form"
import { Input } from "@/components/ui/input"
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select"

const formSchema = z.object({
  username: z.string().min(2, "Username must be at least 2 characters."),
  email: z.string().email("Please enter a valid email."),
  role: z.enum(["admin", "user", "guest"]),
})

export function ProfileForm() {
  const form = useForm>({
    resolver: zodResolver(formSchema),
    defaultValues: { username: "", email: "", role: "user" },
  })

  function onSubmit(values: z.infer) {
    console.log(values)
  }

  return (
    
      
         (
          
            Username
            
            Your public display name.
            
          
        )} />

         (
          
            Email
            
            
          
        )} />

         (
          
            Role
            
              
                
              
              
                Admin
                User
                Guest
              
            
            
          
        )} />

        Submit
      
    
  )
}

Dialog & Sheet

import {
  Dialog, DialogContent, DialogDescription,
  DialogFooter, DialogHeader, DialogTitle, DialogTrigger,
} from "@/components/ui/dialog"
import {
  Sheet, SheetContent, SheetHeader, SheetTitle, SheetTrigger,
} from "@/components/ui/sheet"

// Modal dialog

  Edit profile
  
    
      Edit profile
      Make changes here. Click save when done.
    
    {/* form fields */}
    Save changes
  


// Slide-over panel (side: "left" | "right" | "top" | "bottom")

  Open
  
    Settings
    {/* content */}
  

Card

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


  
    Create project
    Deploy your new project in one-click.
  
  
    
      
        Name
        
      
    
  
  
    Cancel
    Deploy
  

Toast Notifications

// 1. Add Toaster to root layout
import { Toaster } from "@/components/ui/toaster"

export default function RootLayout({ children }) {
  return (
    
      {children}
    
  )
}

// 2. Use toast in components
import { useToast } from "@/components/ui/use-toast"
import { ToastAction } from "@/components/ui/toast"

const { toast } = useToast()

toast({ title: "Success", description: "Changes saved." })

toast({
  variant: "destructive",
  title: "Error",
  description: "Something went wrong.",
  action: Try again,
})

Table

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

const invoices = [
  { invoice: "INV001", status: "Paid", method: "Credit Card", amount: "$250.00" },
  { invoice: "INV002", status: "Pending", method: "PayPal", amount: "$150.00" },
]


  A list of your recent invoices.
  
    
      Invoice
      Status
      Method
      Amount
    
  
  
    {invoices.map((invoice) => (
      
        {invoice.invoice}
        {invoice.status}
        {invoice.method}
        {invoice.amount}
      
    ))}
  

Theming

shadcn/ui uses CSS variables in HSL format. Configure in globals.css:

@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --primary: 222.2 47.4% 11.2%;
    --primary-foreground: 210 40% 98%;
    --secondary: 210 40% 96.1%;
    --muted: 210 40% 96.1%;
    --muted-foreground: 215.4 16.3% 46.9%;
    --destructive: 0 84.2% 60.2%;
    --border: 214.3 31.8% 91.4%;
    --ring: 222.2 84% 4.9%;
    --radius: 0.5rem;
  }

  .dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
    --primary: 210 40% 98%;
    --primary-foreground: 222.2 47.4% 11.2%;
    /* ... mirror all variables for dark mode */
  }
}

Colors reference as hsl(var(--primary)) in Tailwind config. Change the CSS variables to retheme the entire app.

Customizing Components

Since you own the code, modify components directly:

// Add a custom variant to button.tsx
const buttonVariants = cva("...", {
  variants: {
    variant: {
      // ... existing variants
      gradient: "bg-gradient-to-r from-purple-500 to-pink-500 text-white",
    },
    size: {
      // ... existing sizes
      xl: "h-14 rounded-md px-10 text-lg",
    },
  },
})

Component Reference

Next.js Integration

App Router Setup

For Next.js 13+ with App Router, ensure interactive components use "use client":

// src/components/ui/button.tsx
"use client"

import * as React from "react"
import { Slot } from "@radix-ui/react-slot"
// ... rest of component

Layout Integration

Add the Toaster to your root layout:

// app/layout.tsx
import { Toaster } from "@/components/ui/toaster"
import "./globals.css"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    
      
        {children}
        
      
    
  )
}

Server Components

Most shadcn/ui components need "use client". For Server Components, wrap them in a client component or use them in client component children.

CLI Reference

npx shadcn@latest init              # Initialize project
npx shadcn@latest add [component]   # Add specific component
npx shadcn@latest add --all         # Add all components
npx shadcn@latest diff              # Show upstream changes

Best Practices

NEVER Do

References

• Learning Guide — progression from basics to advanced patterns
• Extended Components — Terminal, Dock, Charts, animations, custom hooks
• Official Docs | Radix UI | React Hook Form | Zod