shadcn/ui Complete Guide: Beautiful, Accessible React Components

shadcn/ui has changed how developers think about component libraries in React. Instead of installing a traditional npm package, shadcn/ui lets you copy beautifully designed, accessible components directly into your project. You own the code, you can customize everything, and there is no dependency lock-in. Built on Radix UI primitives and styled with Tailwind CSS, shadcn/ui has become the go-to choice for building production-grade React interfaces in 2026.

What Is shadcn/ui?

shadcn/ui is not a traditional component library. You do not install it as a dependency in your package.json. Instead, it provides a CLI and a registry of beautifully designed components that you copy directly into your project. This means you own every line of code and can customize anything without fighting library abstractions.

Each component is built on top of Radix UI — a headless, unstyled, accessible component library — and styled with Tailwind CSS. This combination gives you WAI-ARIA compliant components with a modern, clean design that you can adapt to any brand or design system.

The key philosophy is: use what you need, change what you want. There is no theming API to learn, no wrapper components to deal with, and no breaking changes from library updates.

# The shadcn/ui approach:
# 1. You run the CLI to add a component
npx shadcn@latest add button

# 2. The component is copied into your project
# src/components/ui/button.tsx is created

# 3. You import and use it like any local component
import { Button } from "@/components/ui/button"

# 4. You own the code - edit it however you want
# No library dependency, no version conflicts

Installation and Setup

shadcn/ui supports multiple React frameworks. The CLI handles the initial setup including creating a components.json configuration file, setting up Tailwind CSS, and creating utility directories.

Next.js Installation

# Create a new Next.js project
npx create-next-app@latest my-app --typescript --tailwind --eslint
cd my-app

# Initialize shadcn/ui
npx shadcn@latest init

# The CLI will ask you:
# - Which style? (default / new-york)
# - Which color? (slate / gray / zinc / neutral / stone)
# - Use CSS variables for colors? (yes)

# Add your first component
npx shadcn@latest add button

# Add multiple components at once
npx shadcn@latest add button card dialog input label

Vite Installation

# Create a Vite + React + TypeScript project
npm create vite@latest my-app -- --template react-ts
cd my-app

# Install Tailwind CSS
npm install -D tailwindcss @tailwindcss/vite

# Update vite.config.ts to include the plugin
# import tailwindcss from "@tailwindcss/vite"
# plugins: [react(), tailwindcss()]

# Configure path aliases in tsconfig.json
# "paths": { "@/*": ["./src/*"] }

# Initialize shadcn/ui
npx shadcn@latest init

Remix Installation

# Create a Remix project with Vite
npx create-remix@latest my-app
cd my-app

# Install and configure Tailwind CSS
npm install -D tailwindcss @tailwindcss/vite

# Initialize shadcn/ui
npx shadcn@latest init

# Add components as needed
npx shadcn@latest add button dialog form

Understanding components.json

The components.json file is the central configuration for shadcn/ui in your project. It tells the CLI where to put components, how to handle styling, and what import aliases to use.

// components.json
{
  "\$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "src/app/globals.css",
    "baseColor": "zinc",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  }
}

Key fields in components.json: style selects the visual style (default or new-york), tailwind.config points to your Tailwind config file, tailwind.css points to your global CSS file, aliases.components maps the import path for components, and aliases.utils maps the path for utility functions like cn().

Using Components

Adding a component is as simple as running a CLI command. The component files are copied into your project at the path specified in components.json.

Button Component

The Button component supports multiple variants (default, destructive, outline, secondary, ghost, link) and sizes (default, sm, lg, icon).

// Install: npx shadcn@latest add button
import { Button } from "@/components/ui/button"

export function ButtonExamples() {
  return (
    <div>
      {/* Variants */}
      <Button variant="default">Default</Button>
      <Button variant="destructive">Delete</Button>
      <Button variant="outline">Outline</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="ghost">Ghost</Button>
      <Button variant="link">Link</Button>

      {/* Sizes */}
      <Button size="sm">Small</Button>
      <Button size="default">Default</Button>
      <Button size="lg">Large</Button>
      <Button size="icon"><IconComponent /></Button>

      {/* With loading state */}
      <Button disabled>
        <Loader2 style={{ animation: "spin 1s linear infinite" }} />
        Please wait
      </Button>
    </div>
  )
}

Dialog Component

The Dialog component provides an accessible modal dialog built on Radix UI Dialog. It handles focus trapping, keyboard navigation, and screen reader announcements.

// Install: npx shadcn@latest add dialog
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog"

export function DialogExample() {
  return (
    <Dialog>
      <DialogTrigger asChild>
        <Button variant="outline">Edit Profile</Button>
      </DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Edit profile</DialogTitle>
          <DialogDescription>
            Make changes to your profile here.
          </DialogDescription>
        </DialogHeader>
        <div>
          <Label htmlFor="name">Name</Label>
          <Input id="name" defaultValue="John Doe" />
        </div>
        <DialogFooter>
          <Button type="submit">Save changes</Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}

Command (cmdk) Component

The Command component is a command palette interface built on cmdk. It provides a searchable list of items with keyboard navigation — perfect for command menus, search dialogs, and comboboxes.

// Install: npx shadcn@latest add command
import {
  Command,
  CommandDialog,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandSeparator,
} from "@/components/ui/command"

export function CommandMenu() {
  return (
    <Command>
      <CommandInput placeholder="Type a command..." />
      <CommandList>
        <CommandEmpty>No results found.</CommandEmpty>
        <CommandGroup heading="Suggestions">
          <CommandItem>Calendar</CommandItem>
          <CommandItem>Search</CommandItem>
          <CommandItem>Calculator</CommandItem>
        </CommandGroup>
        <CommandSeparator />
        <CommandGroup heading="Settings">
          <CommandItem>Profile</CommandItem>
          <CommandItem>Billing</CommandItem>
          <CommandItem>Settings</CommandItem>
        </CommandGroup>
      </CommandList>
    </Command>
  )
}

Table Component

The Table component provides a clean, styled table with support for headers, body rows, footers, and captions.

// Install: npx shadcn@latest add table
import {
  Table, TableBody, TableCaption,
  TableCell, TableHead, TableHeader, TableRow,
} from "@/components/ui/table"

export function TableExample() {
  return (
    <Table>
      <TableCaption>A list of recent invoices.</TableCaption>
      <TableHeader>
        <TableRow>
          <TableHead>Invoice</TableHead>
          <TableHead>Status</TableHead>
          <TableHead>Method</TableHead>
          <TableHead>Amount</TableHead>
        </TableRow>
      </TableHeader>
      <TableBody>
        <TableRow>
          <TableCell>INV001</TableCell>
          <TableCell>Paid</TableCell>
          <TableCell>Credit Card</TableCell>
          <TableCell>\$250.00</TableCell>
        </TableRow>
      </TableBody>
    </Table>
  )
}

Theming and Dark Mode

shadcn/ui uses CSS variables for theming, which makes it easy to create custom color schemes and support dark mode. All colors are defined using HSL values in your global CSS file.

/* globals.css - CSS Variables for theming */
@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --card: 0 0% 100%;
    --card-foreground: 222.2 84% 4.9%;
    --popover: 0 0% 100%;
    --popover-foreground: 222.2 84% 4.9%;
    --primary: 222.2 47.4% 11.2%;
    --primary-foreground: 210 40% 98%;
    --secondary: 210 40% 96.1%;
    --secondary-foreground: 222.2 47.4% 11.2%;
    --muted: 210 40% 96.1%;
    --muted-foreground: 215.4 16.3% 46.9%;
    --accent: 210 40% 96.1%;
    --accent-foreground: 222.2 47.4% 11.2%;
    --destructive: 0 84.2% 60.2%;
    --destructive-foreground: 210 40% 98%;
    --border: 214.3 31.8% 91.4%;
    --input: 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%;
    --secondary: 217.2 32.6% 17.5%;
    --secondary-foreground: 210 40% 98%;
    --muted: 217.2 32.6% 17.5%;
    --muted-foreground: 215 20.2% 65.1%;
    --accent: 217.2 32.6% 17.5%;
    --accent-foreground: 210 40% 98%;
    --destructive: 0 62.8% 30.6%;
    --destructive-foreground: 210 40% 98%;
    --border: 217.2 32.6% 17.5%;
    --input: 217.2 32.6% 17.5%;
    --ring: 212.7 26.8% 83.9%;
  }
}

Dark mode is handled by defining a second set of CSS variables inside a .dark class. When you toggle the dark class on the html or body element, all components automatically switch to dark mode colors.

Setting Up a Theme Provider

Use next-themes (for Next.js) or a custom provider to toggle between light and dark mode. The provider wraps your application and manages the theme state.

// npm install next-themes
// components/theme-provider.tsx
"use client"

import { ThemeProvider as NextThemesProvider } from "next-themes"
import { type ThemeProviderProps } from "next-themes"

export function ThemeProvider({
  children, ...props
}: ThemeProviderProps) {
  return (
    <NextThemesProvider {...props}>
      {children}
    </NextThemesProvider>
  )
}

// app/layout.tsx
import { ThemeProvider } from "@/components/theme-provider"

export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider
          attribute="class"
          defaultTheme="system"
          enableSystem
          disableTransitionOnChange
        >
          {children}
        </ThemeProvider>
      </body>
    </html>
  )
}

Customization with CSS Variables

Since you own the component code, customization is straightforward. You can modify CSS variables for global changes or edit individual component files for specific changes.

The CSS variable approach means you can create entirely new themes by changing a few HSL values. The naming convention uses semantic names like background, foreground, primary, secondary, muted, accent, and destructive.

/* Example: Creating a custom blue theme */
@layer base {
  :root {
    --primary: 221.2 83.2% 53.3%;    /* Blue */
    --primary-foreground: 210 40% 98%;
    --ring: 221.2 83.2% 53.3%;
    --radius: 0.75rem;  /* Rounder corners */
  }
}

/* Example: Creating a brand-colored theme */
@layer base {
  :root {
    /* Convert your brand color to HSL */
    /* Brand color: #6366f1 = 239 84% 67% */
    --primary: 239 84% 67%;
    --primary-foreground: 0 0% 100%;
    --ring: 239 84% 67%;
  }
}

Forms with React Hook Form and Zod

shadcn/ui provides a powerful form system that integrates React Hook Form for state management and Zod for schema-based validation. This gives you type-safe forms with automatic error handling.

Steps to build a form: 1) Define your Zod schema, 2) Create a form with useForm and zodResolver, 3) Use FormField components to connect fields to the form state, 4) Handle submission with the onSubmit callback.

// Install dependencies:
// npx shadcn@latest add form input button
// npm install zod @hookform/resolvers

"use client"

import { zodResolver } from "@hookform/resolvers/zod"
import { useForm } from "react-hook-form"
import { 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"

// Step 1: Define Zod schema
const formSchema = z.object({
  username: z.string().min(2, {
    message: "Username must be at least 2 characters.",
  }),
  email: z.string().email({
    message: "Please enter a valid email address.",
  }),
})

// Step 2: Create the form component
export function ProfileForm() {
  const form = useForm<z.infer<typeof formSchema>>({
    resolver: zodResolver(formSchema),
    defaultValues: {
      username: "",
      email: "",
    },
  })

  function onSubmit(values: z.infer<typeof formSchema>) {
    console.log(values)
  }

  // Step 3: Render form fields
  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)}>
        <FormField
          control={form.control}
          name="username"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Username</FormLabel>
              <FormControl>
                <Input placeholder="shadcn" {...field} />
              </FormControl>
              <FormDescription>
                Your public display name.
              </FormDescription>
              <FormMessage />
            </FormItem>
          )}
        />
        <Button type="submit">Submit</Button>
      </form>
    </Form>
  )
}

Data Tables with TanStack Table

The DataTable component combines shadcn/ui Table with TanStack Table (formerly React Table) for powerful, flexible data table functionality including sorting, filtering, pagination, and row selection.

Building a data table involves: 1) Defining column definitions with accessorKey and header, 2) Creating a DataTable component that uses useReactTable, 3) Rendering table headers and rows using the flexRender utility.

// Install: npx shadcn@latest add table
// npm install @tanstack/react-table

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

// Step 1: Define columns
type Payment = {
  id: string
  amount: number
  status: "pending" | "processing" | "success" | "failed"
  email: string
}

const columns: ColumnDef<Payment>[] = [
  {
    accessorKey: "status",
    header: "Status",
  },
  {
    accessorKey: "email",
    header: "Email",
  },
  {
    accessorKey: "amount",
    header: () => <div>Amount</div>,
    cell: ({ row }) => {
      const amount = parseFloat(row.getValue("amount"))
      const formatted = new Intl.NumberFormat("en-US", {
        style: "currency",
        currency: "USD",
      }).format(amount)
      return <div>{formatted}</div>
    },
  },
]

// Step 2: Create DataTable component
function DataTable<TData, TValue>({
  columns, data,
}: {
  columns: ColumnDef<TData, TValue>[]
  data: TData[]
}) {
  const [sorting, setSorting] = React.useState<SortingState>([])
  const table = useReactTable({
    data,
    columns,
    getCoreRowModel: getCoreRowModel(),
    getPaginationRowModel: getPaginationRowModel(),
    onSortingChange: setSorting,
    getSortedRowModel: getSortedRowModel(),
    state: { sorting },
  })

  return (
    <Table>
      <TableHeader>
        {table.getHeaderGroups().map((hg) => (
          <TableRow key={hg.id}>
            {hg.headers.map((header) => (
              <TableHead key={header.id}>
                {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>
  )
}

Accessibility Features

Because shadcn/ui is built on Radix UI primitives, every component follows WAI-ARIA guidelines out of the box. This includes proper roles, keyboard navigation, focus management, and screen reader support.

• All interactive components support full keyboard navigation (Tab, Enter, Space, Arrow keys, Escape)
• Focus is trapped inside modal dialogs and returned to the trigger on close
• ARIA attributes (role, aria-expanded, aria-selected, aria-label) are managed automatically
• Screen readers announce component state changes (open/closed, selected, checked)
• Color contrast meets WCAG 2.1 AA standards in the default theme
• Components handle touch targets and responsive behavior for mobile devices

// Accessibility is built-in with Radix UI
// Example: Dialog with proper focus management
<Dialog>
  <DialogTrigger asChild>
    {/* Trigger receives focus on close */}
    <Button>Open Dialog</Button>
  </DialogTrigger>
  <DialogContent>
    {/* Focus is trapped inside */}
    {/* Escape key closes the dialog */}
    {/* aria-describedby auto-set */}
    <DialogTitle>Accessible Dialog</DialogTitle>
    <DialogDescription>
      Screen readers announce this description.
    </DialogDescription>
    <Button>First focusable element</Button>
  </DialogContent>
</Dialog>

Creating Custom Components

You can create your own components following the shadcn/ui pattern: use Radix UI (or another headless library) for behavior, Tailwind CSS for styling, and the cn() utility for conditional classes. This keeps your custom components consistent with the rest of your shadcn/ui components.

// Example: Custom StatusBadge component
// following the shadcn/ui pattern
import * as React from "react"
import { cva, type VariantProps } from "class-variance-authority"
import { cn } from "@/lib/utils"

const statusBadgeVariants = cva(
  "inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-semibold transition-colors focus:outline-none focus:ring-2 focus:ring-ring",
  {
    variants: {
      status: {
        online: "bg-green-100 text-green-800 dark:bg-green-900 dark:text-green-300",
        offline: "bg-gray-100 text-gray-800 dark:bg-gray-800 dark:text-gray-300",
        busy: "bg-red-100 text-red-800 dark:bg-red-900 dark:text-red-300",
        away: "bg-yellow-100 text-yellow-800 dark:bg-yellow-900 dark:text-yellow-300",
      },
    },
    defaultVariants: {
      status: "offline",
    },
  }
)

interface StatusBadgeProps
  extends React.HTMLAttributes<HTMLDivElement>,
    VariantProps<typeof statusBadgeVariants> {}

function StatusBadge({ status, ...props }: StatusBadgeProps) {
  return (
    <div
      {...props}
      // cn() merges classes without conflicts
    />
  )
}

export { StatusBadge, statusBadgeVariants }

Tailwind CSS Integration

shadcn/ui is designed to work seamlessly with Tailwind CSS. The cn() utility function (built on clsx and tailwind-merge) is essential for combining component classes with custom classes without conflicts.

tailwind-merge intelligently resolves class conflicts. For example, if a component has bg-primary and you pass bg-red-500, tailwind-merge ensures only bg-red-500 is applied, avoiding Tailwind CSS specificity issues.

// src/lib/utils.ts - The cn() utility
import { type ClassValue, clsx } from "clsx"
import { twMerge } from "tailwind-merge"

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

// Usage: combining component + custom classes
import { cn } from "@/lib/utils"

// Without cn(): "bg-primary bg-red-500"
// Both classes applied = unpredictable result

// With cn(): "bg-red-500"
// tailwind-merge resolves the conflict

function MyComponent({ isActive }: { isActive: boolean }) {
  return (
    <div
      // cn() handles conditional classes cleanly
    >
      Content
    </div>
  )
}

Migrating from Other UI Libraries

If you are migrating from Material UI, Chakra UI, Ant Design, or another component library, shadcn/ui offers a gradual migration path. You can add shadcn/ui components alongside your existing library and migrate one component at a time.

Migration strategy: 1) Install shadcn/ui alongside your existing library, 2) Replace one component at a time starting with the simplest ones (Button, Input, Badge), 3) Update form components using shadcn/ui Form with React Hook Form, 4) Migrate complex components (DataTable, Combobox, Command) last, 5) Remove the old library once all components are replaced.

Best Practices

• Use the CLI to add components — do not copy files manually from GitHub
• Keep components.json in version control so the CLI works for all team members
• Use the cn() utility for all conditional class logic instead of manual string concatenation
• Customize CSS variables in globals.css for consistent theming across all components
• Do not modify the Radix UI primitive behavior unless you understand the accessibility implications
• Use React Hook Form with Zod for all forms — it provides type safety and automatic error handling
• Wrap shadcn/ui components in your own components for project-specific defaults and abstractions
• Keep your components directory organized — group related components in subdirectories
• Update components periodically by re-running the CLI add command and reviewing the diff
• Use the new-york style variant for a more polished, compact design

Frequently Asked Questions