shadcn/ui - Component Library

progressive_disclosure: entry_point: summary, when_to_use, quick_start estimated_tokens: entry: 85 full: 4800

Summary

shadcn/ui is a collection of re-usable React components built with Radix UI primitives and styled with Tailwind CSS. Unlike traditional component libraries, shadcn/ui components are copied directly into your project, giving you full ownership and customization control. Components are accessible, customizable, and open source.

Core Philosophy: Copy-paste components, not npm packages. You own the code.

When to Use

Use shadcn/ui when:

• Building React applications with Tailwind CSS

• Need accessible, production-ready UI components

• Want full control over component code and styling

• Prefer composition over configuration

• Building with Next.js, Vite, Remix, or Astro

• Need dark mode support out of the box

• Want TypeScript-first components

Don't use when:

• Not using Tailwind CSS (core styling dependency)

• Need legacy browser support (uses modern CSS features)

• Prefer packaged npm libraries over code ownership

• Building non-React frameworks (Vue, Svelte, Angular)

Quick Start

Installation

Initialize shadcn/ui in your project

npx shadcn-ui@latest init

Follow interactive prompts:

- TypeScript? (yes/no)

- Style: Default/New York

- Base color: Slate/Gray/Zinc/Neutral/Stone

- CSS variables: (yes/no)

- React Server Components: (yes/no)

- components.json location

- Tailwind config location

- CSS file location

- Import alias (@/components)

Add Your First Component

Add individual components

npx shadcn-ui@latest add button npx shadcn-ui@latest add card npx shadcn-ui@latest add dialog

Add multiple components at once

npx shadcn-ui@latest add button card dialog form input

Basic Usage

import { Button } from "@/components/ui/button" import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card"

export default function Example() { return ( <Card> <CardHeader> <CardTitle>Welcome</CardTitle> </CardHeader> <CardContent> <Button>Click me</Button> </CardContent> </Card> ) }

Architecture

Copy-Paste Philosophy

Key Difference from Traditional Libraries:

• Traditional: npm install component-library → locked to package versions

• shadcn/ui: Components copied to components/ui/ → you own the code

Benefits:

• Full customization control

• No breaking changes from package updates

• Easy to modify for specific needs

• Transparent implementation

• Tree-shakeable by default

Component Structure

src/ ├── components/ │ └── ui/ │ ├── button.tsx # Component implementation │ ├── card.tsx # Owns its code │ ├── dialog.tsx # Modifiable │ └── ... ├── lib/ │ └── utils.ts # cn() helper for class merging └── app/ └── globals.css # Tailwind directives + CSS variables

Technology Stack

Core Dependencies:

• Radix UI: Accessible component primitives (headless UI)

• Tailwind CSS: Utility-first styling

• TypeScript: Type safety

• class-variance-authority (CVA): Variant management

• clsx: Class name concatenation

• tailwind-merge: Conflict-free class merging

Radix UI Integration:

// shadcn/ui components wrap Radix primitives import * as DialogPrimitive from "@radix-ui/react-dialog"

// Add styling and variants const Dialog = DialogPrimitive.Root const DialogTrigger = DialogPrimitive.Trigger const DialogContent = React.forwardRef<...>( ({ className, children, ...props }, ref) => ( <DialogPrimitive.Content ref={ref} className={cn("fixed ...", className)} {...props} /> ) )

Configuration

components.json

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

Key Options:

• style : "default" or "new-york" (design variants)

• rsc : React Server Components support

• cssVariables : Use CSS variables for theming

• prefix : Tailwind class prefix (optional)

Tailwind Configuration

// tailwind.config.ts import type { Config } from "tailwindcss"

const config = { darkMode: ["class"], content: [ './pages//*.{ts,tsx}', './components//.{ts,tsx}', './app/**/.{ts,tsx}', './src/**/*.{ts,tsx}', ], prefix: "", theme: { container: { center: true, padding: "2rem", screens: { "2xl": "1400px", }, }, extend: { colors: { border: "hsl(var(--border))", input: "hsl(var(--input))", ring: "hsl(var(--ring))", background: "hsl(var(--background))", foreground: "hsl(var(--foreground))", primary: { DEFAULT: "hsl(var(--primary))", foreground: "hsl(var(--primary-foreground))", }, secondary: { DEFAULT: "hsl(var(--secondary))", foreground: "hsl(var(--secondary-foreground))", }, destructive: { DEFAULT: "hsl(var(--destructive))", foreground: "hsl(var(--destructive-foreground))", }, muted: { DEFAULT: "hsl(var(--muted))", foreground: "hsl(var(--muted-foreground))", }, accent: { DEFAULT: "hsl(var(--accent))", foreground: "hsl(var(--accent-foreground))", }, popover: { DEFAULT: "hsl(var(--popover))", foreground: "hsl(var(--popover-foreground))", }, card: { DEFAULT: "hsl(var(--card))", foreground: "hsl(var(--card-foreground))", }, }, borderRadius: { lg: "var(--radius)", md: "calc(var(--radius) - 2px)", sm: "calc(var(--radius) - 4px)", }, keyframes: { "accordion-down": { from: { height: "0" }, to: { height: "var(--radix-accordion-content-height)" }, }, "accordion-up": { from: { height: "var(--radix-accordion-content-height)" }, to: { height: "0" }, }, }, animation: { "accordion-down": "accordion-down 0.2s ease-out", "accordion-up": "accordion-up 0.2s ease-out", }, }, }, plugins: [require("tailwindcss-animate")], } satisfies Config

export default config

CSS Variables (globals.css)

@tailwind base; @tailwind components; @tailwind utilities;

@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%; --card: 222.2 84% 4.9%; --card-foreground: 210 40% 98%; --popover: 222.2 84% 4.9%; --popover-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%; } }

@layer base {

• { @apply border-border; } body { @apply bg-background text-foreground; } }

Component Catalog

Button

import { Button } from "@/components/ui/button"

// Variants <Button variant="default">Default</Button> <Button variant="destructive">Destructive</Button> <Button variant="outline">Outline</Button> <Button variant="secondary">Secondary</Button> <Button variant="ghost">Ghost</Button> <Button variant="link">Link</Button>

// Sizes <Button size="default">Default</Button> <Button size="sm">Small</Button> <Button size="lg">Large</Button> <Button size="icon"><Icon /></Button>

// States <Button disabled>Disabled</Button> <Button asChild> <Link href="/about">As Link</Link> </Button>

Implementation Pattern (CVA):

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 focus-visible:outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50", { 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 hover:text-accent-foreground", secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80", 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", }, } )

Card

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

<Card> <CardHeader> <CardTitle>Card Title</CardTitle> <CardDescription>Card description goes here</CardDescription> </CardHeader> <CardContent> <p>Card content</p> </CardContent> <CardFooter> <Button>Action</Button> </CardFooter> </Card>

Dialog (Modal)

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

<Dialog> <DialogTrigger asChild> <Button>Open Dialog</Button> </DialogTrigger> <DialogContent> <DialogHeader> <DialogTitle>Are you sure?</DialogTitle> <DialogDescription> This action cannot be undone. </DialogDescription> </DialogHeader> <DialogFooter> <Button variant="outline">Cancel</Button> <Button>Confirm</Button> </DialogFooter> </DialogContent> </Dialog>

Form (with react-hook-form + zod)

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

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.", }), })

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) }

return ( <Form {...form}> <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-8"> <FormField control={form.control} name="username" render={({ field }) => ( <FormItem> <FormLabel>Username</FormLabel> <FormControl> <Input placeholder="shadcn" {...field} /> </FormControl> <FormDescription> This is your public display name. </FormDescription> <FormMessage /> </FormItem> )} /> <FormField control={form.control} name="email" render={({ field }) => ( <FormItem> <FormLabel>Email</FormLabel> <FormControl> <Input type="email" placeholder="user@example.com" {...field} /> </FormControl> <FormMessage /> </FormItem> )} /> <Button type="submit">Submit</Button> </form> </Form> ) }

Table

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

<Table> <TableCaption>A list of your recent invoices.</TableCaption> <TableHeader> <TableRow> <TableHead>Invoice</TableHead> <TableHead>Status</TableHead> <TableHead>Method</TableHead> <TableHead className="text-right">Amount</TableHead> </TableRow> </TableHeader> <TableBody> <TableRow> <TableCell>INV001</TableCell> <TableCell>Paid</TableCell> <TableCell>Credit Card</TableCell> <TableCell className="text-right">$250.00</TableCell> </TableRow> </TableBody> </Table>

Additional Components

Available via CLI:

• accordion

• Collapsible content sections

• alert

• Contextual feedback messages

• alert-dialog

• Interrupting modal dialogs

• avatar

• User profile images

• badge

• Status indicators

• calendar

• Date picker

• checkbox

• Binary input

• command

• Command palette (⌘K menu)

• context-menu

• Right-click menus

• dropdown-menu

• Dropdown menus

• hover-card

• Hover tooltips

• input

• Text input

• label

• Form labels

• menubar

• Application menu bar

• navigation-menu

• Site navigation

• popover

• Floating panels

• progress

• Progress indicators

• radio-group

• Radio button groups

• scroll-area

• Custom scrollbars

• select

• Dropdown selects

• separator

• Visual dividers

• sheet

• Side panels

• skeleton

• Loading placeholders

• slider

• Range input

• switch

• Toggle switch

• tabs

• Tab navigation

• textarea

• Multi-line input

• toast

• Notification toasts

• toggle

• Toggle button

• tooltip

• Hover tooltips

Theming

Color Customization

Change base color scheme:

Regenerate components with new base color

npx shadcn-ui@latest init

Choose new base: Slate, Gray, Zinc, Neutral, Stone

Manual color override (globals.css):

:root { --primary: 210 100% 50%; /* HSL: Blue */ --primary-foreground: 0 0% 100%; }

.dark { --primary: 210 100% 60%; /* Lighter blue for dark mode */ }

Custom Variants

// Extend button variants const buttonVariants = cva( "...", { variants: { variant: { // ...existing variants gradient: "bg-gradient-to-r from-purple-500 to-pink-500 text-white", }, }, } )

// Usage <Button variant="gradient">Gradient Button</Button>

Theme Switching

// Using next-themes import { ThemeProvider } from "next-themes"

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

// Theme toggle component import { Moon, Sun } from "lucide-react" import { useTheme } from "next-themes" import { Button } from "@/components/ui/button"

export function ThemeToggle() { const { setTheme, theme } = useTheme()

return ( <Button variant="ghost" size="icon" onClick={() => setTheme(theme === "light" ? "dark" : "light")} > <Sun className="h-[1.2rem] w-[1.2rem] rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" /> <Moon className="absolute h-[1.2rem] w-[1.2rem] rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" /> <span className="sr-only">Toggle theme</span> </Button> ) }

Dark Mode

Setup with Next.js

npm install next-themes

// app/providers.tsx "use client"

import { ThemeProvider } from "next-themes"

export function Providers({ children }: { children: React.ReactNode }) { return ( <ThemeProvider attribute="class" defaultTheme="system" enableSystem> {children} </ThemeProvider> ) }

// app/layout.tsx import { Providers } from "./providers"

export default function RootLayout({ children }) { return ( <html lang="en" suppressHydrationWarning> <body> <Providers>{children}</Providers> </body> </html> ) }

Dark Mode Utilities

// Force dark mode for specific section <div className="dark"> <Card>Always dark, regardless of theme</Card> </div>

// Conditional styling <div className="bg-white dark:bg-slate-950"> <p className="text-slate-900 dark:text-slate-50"> Adapts to theme </p> </div>

Next.js Integration

App Router Setup

Create Next.js app with TypeScript and Tailwind

npx create-next-app@latest my-app --typescript --tailwind --app

Initialize shadcn/ui

cd my-app npx shadcn-ui@latest init

Add components

npx shadcn-ui@latest add button card form

Server Components

// app/page.tsx (Server Component by default) import { Button } from "@/components/ui/button"

export default function HomePage() { return ( <main> <h1>Welcome</h1> {/* Static components work in Server Components */} <Button asChild> <a href="/about">Learn More</a> </Button> </main> ) }

Client Components

// app/interactive.tsx "use client"

import { useState } from "react" import { Button } from "@/components/ui/button" import { Dialog, DialogContent, DialogTrigger } from "@/components/ui/dialog"

export function InteractiveSection() { const [open, setOpen] = useState(false)

return ( <Dialog open={open} onOpenChange={setOpen}> <DialogTrigger asChild> <Button>Open Dialog</Button> </DialogTrigger> <DialogContent> <p>Client-side interactivity</p> </DialogContent> </Dialog> ) }

Route Handlers

// app/api/submit/route.ts import { NextResponse } from "next/server" import { z } from "zod"

const formSchema = z.object({ email: z.string().email(), message: z.string().min(10), })

export async function POST(request: Request) { try { const body = await request.json() const validatedData = formSchema.parse(body)

// Process form data
return NextResponse.json({ success: true })

} catch (error) { if (error instanceof z.ZodError) { return NextResponse.json({ errors: error.errors }, { status: 400 }) } return NextResponse.json({ error: "Internal error" }, { status: 500 }) } }

Accessibility

ARIA Support

All shadcn/ui components include proper ARIA attributes via Radix UI:

// Dialog automatically includes: // - role="dialog" // - aria-describedby // - aria-labelledby // - Focus trap // - Escape key handler <Dialog> <DialogContent> {/* Automatically accessible */} </DialogContent> </Dialog>

// Button includes: // - role="button" // - tabindex="0" // - Keyboard activation (Space/Enter) <Button>Accessible by default</Button>

Keyboard Navigation

Built-in keyboard support:

• Tab / Shift+Tab

• Navigate between interactive elements

• Enter / Space

• Activate buttons

• Escape

• Close dialogs, dropdowns, popovers

• Arrow keys

• Navigate menus, select options, radio groups

• Home / End

• Jump to first/last in lists

Example: Command Palette:

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

// ⌘K to open <CommandDialog open={open} onOpenChange={setOpen}> <CommandInput placeholder="Type a command..." /> <CommandList> <CommandEmpty>No results found.</CommandEmpty> <CommandGroup heading="Suggestions"> <CommandItem>Calendar</CommandItem> <CommandItem>Search Emoji</CommandItem> <CommandItem>Calculator</CommandItem> </CommandGroup> </CommandList> </CommandDialog>

Screen Reader Support

// Visually hidden but accessible to screen readers <span className="sr-only">Close dialog</span>

// Skip navigation links <a href="#main-content" className="sr-only focus:not-sr-only"> Skip to main content </a>

// Descriptive labels <FormLabel htmlFor="email">Email address</FormLabel> <Input id="email" type="email" aria-describedby="email-description" aria-invalid={!!errors.email} /> <FormDescription id="email-description"> We'll never share your email. </FormDescription>

Focus Management

// Focus trap in Dialog (automatic) <Dialog> <DialogContent> {/* Focus stays within dialog until closed */} </DialogContent> </Dialog>

// Custom focus management import { useRef, useEffect } from "react"

function CustomComponent() { const inputRef = useRef<HTMLInputElement>(null)

useEffect(() => { inputRef.current?.focus() }, [])

return <Input ref={inputRef} /> }

Composition Patterns

Compound Components

// Card composition <Card> <CardHeader> <CardTitle>Title</CardTitle> <CardDescription>Description</CardDescription> </CardHeader> <CardContent>Content</CardContent> <CardFooter>Footer</CardFooter> </Card>

// Form composition <Form {...form}> <FormField control={form.control} name="field" render={({ field }) => ( <FormItem> <FormLabel>Label</FormLabel> <FormControl> <Input {...field} /> </FormControl> <FormDescription>Help text</FormDescription> <FormMessage /> </FormItem> )} /> </Form>

Polymorphic Components (asChild)

// Render Button as Link import { Button } from "@/components/ui/button" import Link from "next/link"

<Button asChild> <Link href="/dashboard">Go to Dashboard</Link> </Button>

// Render as custom component <Button asChild> <motion.button whileHover={{ scale: 1.05 }} whileTap={{ scale: 0.95 }}

Animated Button

</motion.button> </Button>

How it works (Radix Slot):

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

interface ButtonProps { asChild?: boolean }

const Button = ({ asChild, ...props }: ButtonProps) => { const Comp = asChild ? Slot : "button" return <Comp {...props} /> }

Custom Compositions

// Create custom card variant export function PricingCard({ title, price, features, highlighted }: PricingCardProps) { return ( <Card className={cn(highlighted && "border-primary")}> <CardHeader> <CardTitle>{title}</CardTitle> <CardDescription className="text-3xl font-bold"> ${price}/mo </CardDescription> </CardHeader> <CardContent> <ul className="space-y-2"> {features.map((feature) => ( <li key={feature} className="flex items-center"> <Check className="mr-2 h-4 w-4 text-primary" /> {feature} </li> ))} </ul> </CardContent> <CardFooter> <Button className="w-full" variant={highlighted ? "default" : "outline"}> Get Started </Button> </CardFooter> </Card> ) }

CLI Commands

Initialize

Interactive init

npx shadcn-ui@latest init

Non-interactive with defaults

npx shadcn-ui@latest init -y

Specify options

npx shadcn-ui@latest init --typescript --tailwind

Add Components

Single component

npx shadcn-ui@latest add button

Multiple components

npx shadcn-ui@latest add button card dialog form

All components (not recommended - adds everything)

npx shadcn-ui@latest add --all

Specific version

npx shadcn-ui@latest add button@1.0.0

Overwrite existing

npx shadcn-ui@latest add button --overwrite

Different path

npx shadcn-ui@latest add button --path src/components/ui

Diff Components

Check for component updates

npx shadcn-ui@latest diff

Diff specific component

npx shadcn-ui@latest diff button

Show what would change

npx shadcn-ui@latest diff --check

Update Components

Update all components

npx shadcn-ui@latest update

Update specific components

npx shadcn-ui@latest update button card

Preview changes before applying

npx shadcn-ui@latest update --dry-run

Advanced Patterns

Custom Hooks

// useToast hook (built-in with toast component) import { useToast } from "@/components/ui/use-toast"

function MyComponent() { const { toast } = useToast()

return ( <Button onClick={() => { toast({ title: "Scheduled: Catch up", description: "Friday, February 10, 2023 at 5:57 PM", }) }} > Show Toast </Button> ) }

// Custom form hook import { useForm } from "react-hook-form" import { zodResolver } from "@hookform/resolvers/zod"

function useFormWithToast<T extends z.ZodType>(schema: T) { const { toast } = useToast() const form = useForm({ resolver: zodResolver(schema), })

const handleSubmit = form.handleSubmit(async (data) => { try { // Submit logic toast({ title: "Success!" }) } catch (error) { toast({ title: "Error", variant: "destructive" }) } })

return { form, handleSubmit } }

Responsive Design

// Mobile-first responsive components <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4"> <Card>Mobile: 1 col, Tablet: 2 col, Desktop: 3 col</Card> </div>

// Responsive dialog (sheet on mobile, dialog on desktop) import { useMediaQuery } from "@/hooks/use-media-query" import { Dialog, DialogContent } from "@/components/ui/dialog" import { Sheet, SheetContent } from "@/components/ui/sheet"

function ResponsiveModal({ children, ...props }) { const isDesktop = useMediaQuery("(min-width: 768px)")

if (isDesktop) { return ( <Dialog {...props}> <DialogContent>{children}</DialogContent> </Dialog> ) }

return ( <Sheet {...props}> <SheetContent>{children}</SheetContent> </Sheet> ) }

Animation Variants

// Using Framer Motion with shadcn/ui import { motion } from "framer-motion" import { Card } from "@/components/ui/card"

const MotionCard = motion(Card)

<MotionCard initial={{ opacity: 0, y: 20 }} animate={{ opacity: 1, y: 0 }} transition={{ duration: 0.3 }}

Animated Card </MotionCard>

// Staggered list animation const container = { hidden: { opacity: 0 }, show: { opacity: 1, transition: { staggerChildren: 0.1 } } }

const item = { hidden: { opacity: 0, y: 20 }, show: { opacity: 1, y: 0 } }

<motion.ul variants={container} initial="hidden" animate="show"> {items.map((item) => ( <motion.li key={item.id} variants={item}> <Card>{item.content}</Card> </motion.li> ))} </motion.ul>

Best Practices

Code Organization:

• Keep shadcn/ui components in components/ui/ (don't mix with app components)

• Create custom compositions in components/ (outside ui/)

• Use lib/utils.ts for shared utilities

Customization:

• Modify components directly in your project (you own the code)

• Use CSS variables for theme-wide changes

• Extend variants with CVA for new styles

• Don't edit components.json manually (use CLI)

Performance:

• Tree-shaking automatic (only imports what you use)

• Use asChild to avoid unnecessary wrapper elements

• Lazy load heavy components (Calendar, Command)

• Prefer Server Components when possible (Next.js)

Accessibility:

• Don't remove ARIA attributes from components

• Test keyboard navigation for custom compositions

• Maintain focus management in dialogs/modals

• Use semantic HTML with asChild when applicable

TypeScript:

• Leverage exported types (ButtonProps, CardProps, etc.)

• Use VariantProps for variant type safety

• Add strict null checks for form validation

Troubleshooting

Import errors:

Check path aliases in tsconfig.json

{ "compilerOptions": { "baseUrl": ".", "paths": { "@/": ["./src/"] } } }

Tailwind classes not applying:

// Ensure content paths include your components // tailwind.config.ts content: [ './src/components//*.{ts,tsx}', // Add this './src/app//*.{ts,tsx}', ]

Dark mode not working:

// Add suppressHydrationWarning to <html> <html lang="en" suppressHydrationWarning>

Form validation not triggering:

// Ensure FormMessage is included in FormField <FormField> <FormItem> <FormControl>...</FormControl> <FormMessage /> {/* Required for errors */} </FormItem> </FormField>

Resources

• Official Docs: https://ui.shadcn.com

• Component Source: https://github.com/shadcn-ui/ui

• Radix UI Docs: https://www.radix-ui.com

• Tailwind CSS: https://tailwindcss.com

• CVA Docs: https://cva.style/docs

• Examples: https://ui.shadcn.com/examples

• Community: https://discord.gg/shadcn-ui