name	frontend-shadcn
description	DEFAULT foundation component library for all React/Next.js UI needs. Use as the starting point for any project needing buttons, inputs, dialogs, forms, tables, navigation, modals, dropdowns, and other standard UI elements. Built on Radix UI + Tailwind CSS. Check shadcn FIRST before reaching for other libraries.
allowed-tools	Read, Edit, Write, Bash (*)

shadcn/ui Component Library

Overview

shadcn/ui is NOT a component library you install via npm. It's a collection of re-usable components that you copy and paste into your project. You OWN the code.

Philosophy: Copy-paste → Own the code → Customize freely

Built on: Radix UI (accessibility) + Tailwind CSS (styling) + CVA (variants)

When to Use This Skill

Starting ANY new React/Next.js project
Need standard UI components (buttons, inputs, dialogs, etc.)
Building forms, tables, navigation
Need accessible, production-ready components
User asks for "basic UI", "form", "modal", "dropdown", etc.

This is your DEFAULT starting point. Always check shadcn/ui first.

Quick Start

Project Setup

# Initialize shadcn/ui in your project
npx shadcn@latest init

# Answer prompts:
# - Style: Default or New York
# - Base color: Slate, Gray, Zinc, Neutral, Stone
# - CSS variables: Yes (recommended)

Add Components

# Add single component
npx shadcn@latest add button

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

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

Complete Component Reference

Forms & Inputs

Component	Command	Use Case
Button	`add button`	Primary actions, CTAs
Input	`add input`	Text fields
Textarea	`add textarea`	Multi-line text
Select	`add select`	Dropdown selection
Native Select	`add native-select`	Native HTML select
Checkbox	`add checkbox`	Boolean options
Radio Group	`add radio-group`	Single choice from options
Switch	`add switch`	Toggle on/off
Slider	`add slider`	Range selection
Input OTP	`add input-otp`	One-time password input
Form	`add form`	Form with react-hook-form + zod
Label	`add label`	Form field labels
Field	`add field`	Form field wrapper

// Button variants
<Button>Default</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="destructive">Delete</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="link">Link</Button>
<Button size="sm">Small</Button>
<Button size="lg">Large</Button>
<Button size="icon"><Icon /></Button>

// Form example with validation
import { useForm } from "react-hook-form"
import { zodResolver } from "@hookform/resolvers/zod"
import * as z from "zod"

const schema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
})

export function LoginForm() {
  const form = useForm({
    resolver: zodResolver(schema),
  })

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)}>
        <FormField
          control={form.control}
          name="email"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Email</FormLabel>
              <FormControl>
                <Input {...field} />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />
        <Button type="submit">Login</Button>
      </form>
    </Form>
  )
}

Overlays & Modals

Component	Command	Use Case
Dialog	`add dialog`	Modal windows, confirmations
Alert Dialog	`add alert-dialog`	Destructive action confirmations
Sheet	`add sheet`	Side panels (mobile nav, filters)
Drawer	`add drawer`	Bottom sheets (mobile)
Popover	`add popover`	Floating content, pickers
Tooltip	`add tooltip`	Hover hints
Hover Card	`add hover-card`	Rich hover previews
Context Menu	`add context-menu`	Right-click menus
Dropdown Menu	`add dropdown-menu`	Action menus

// Dialog example
<Dialog>
  <DialogTrigger asChild>
    <Button>Open</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Edit Profile</DialogTitle>
      <DialogDescription>
        Make changes to your profile here.
      </DialogDescription>
    </DialogHeader>
    {/* content */}
    <DialogFooter>
      <Button type="submit">Save</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>

// Sheet (side panel)
<Sheet>
  <SheetTrigger asChild>
    <Button variant="outline">Open Menu</Button>
  </SheetTrigger>
  <SheetContent side="left"> {/* left | right | top | bottom */}
    <SheetHeader>
      <SheetTitle>Menu</SheetTitle>
    </SheetHeader>
    {/* navigation links */}
  </SheetContent>
</Sheet>

Navigation

Component	Command	Use Case
Navigation Menu	`add navigation-menu`	Main site navigation
Menubar	`add menubar`	App menubar (File, Edit, View)
Breadcrumb	`add breadcrumb`	Page hierarchy
Pagination	`add pagination`	Page navigation
Tabs	`add tabs`	Content sections
Command	`add command`	Command palette (⌘K)
Sidebar	`add sidebar`	App sidebar navigation

// Tabs example
<Tabs defaultValue="account">
  <TabsList>
    <TabsTrigger value="account">Account</TabsTrigger>
    <TabsTrigger value="password">Password</TabsTrigger>
  </TabsList>
  <TabsContent value="account">Account settings...</TabsContent>
  <TabsContent value="password">Password settings...</TabsContent>
</Tabs>

// Command palette (cmdk)
<Command>
  <CommandInput placeholder="Type a command..." />
  <CommandList>
    <CommandEmpty>No results found.</CommandEmpty>
    <CommandGroup heading="Suggestions">
      <CommandItem>Calendar</CommandItem>
      <CommandItem>Search</CommandItem>
      <CommandItem>Settings</CommandItem>
    </CommandGroup>
  </CommandList>
</Command>

Layout & Structure

Component	Command	Use Case
Card	`add card`	Content containers
Accordion	`add accordion`	Collapsible sections
Collapsible	`add collapsible`	Toggle content visibility
Separator	`add separator`	Visual dividers
Aspect Ratio	`add aspect-ratio`	Fixed aspect containers
Scroll Area	`add scroll-area`	Custom scrollbars
Resizable	`add resizable`	Resizable panels

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

// Accordion
<Accordion type="single" collapsible>
  <AccordionItem value="item-1">
    <AccordionTrigger>Is it accessible?</AccordionTrigger>
    <AccordionContent>
      Yes. It follows WAI-ARIA patterns.
    </AccordionContent>
  </AccordionItem>
</Accordion>

Data Display

Component	Command	Use Case
Table	`add table`	Basic tables
Data Table	`add data-table`	Advanced tables (sorting, filtering)
Avatar	`add avatar`	User images
Badge	`add badge`	Status labels, tags
Calendar	`add calendar`	Date picker calendar
Date Picker	`add date-picker`	Date selection
Carousel	`add carousel`	Image/content sliders
Chart	`add chart`	Data visualization (Recharts)

// Table
<Table>
  <TableHeader>
    <TableRow>
      <TableHead>Name</TableHead>
      <TableHead>Email</TableHead>
      <TableHead>Status</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell>John Doe</TableCell>
      <TableCell>john@example.com</TableCell>
      <TableCell><Badge>Active</Badge></TableCell>
    </TableRow>
  </TableBody>
</Table>

// Badge variants
<Badge>Default</Badge>
<Badge variant="secondary">Secondary</Badge>
<Badge variant="destructive">Error</Badge>
<Badge variant="outline">Outline</Badge>

Feedback

Component	Command	Use Case
Alert	`add alert`	Inline messages
Toast	`add toast`	Brief notifications
Sonner	`add sonner`	Better toast notifications
Progress	`add progress`	Loading progress
Skeleton	`add skeleton`	Loading placeholders
Spinner	`add spinner`	Loading indicator
Empty	`add empty`	Empty state placeholder

// Alert
<Alert>
  <AlertTitle>Heads up!</AlertTitle>
  <AlertDescription>
    You can add components to your app.
  </AlertDescription>
</Alert>

<Alert variant="destructive">
  <AlertTitle>Error</AlertTitle>
  <AlertDescription>Something went wrong.</AlertDescription>
</Alert>

// Toast (using Sonner - recommended)
import { toast } from "sonner"

// Trigger toast
toast.success("Profile updated!")
toast.error("Something went wrong")
toast.loading("Saving...")

// Skeleton loading
<div className="space-y-2">
  <Skeleton className="h-4 w-[250px]" />
  <Skeleton className="h-4 w-[200px]" />
</div>

Utility

Component	Command	Use Case
Toggle	`add toggle`	On/off button
Toggle Group	`add toggle-group`	Multiple toggles
Combobox	`add combobox`	Searchable select
Typography	`add typography`	Text styles
Kbd	`add kbd`	Keyboard shortcut hints
Button Group	`add button-group`	Grouped buttons
Input Group	`add input-group`	Input with addons
Item	`add item`	List item component

// Combobox (searchable select)
<Popover open={open} onOpenChange={setOpen}>
  <PopoverTrigger asChild>
    <Button variant="outline" role="combobox">
      {value || "Select framework..."}
    </Button>
  </PopoverTrigger>
  <PopoverContent>
    <Command>
      <CommandInput placeholder="Search..." />
      <CommandList>
        <CommandEmpty>No results.</CommandEmpty>
        <CommandGroup>
          {frameworks.map((framework) => (
            <CommandItem
              key={framework.value}
              onSelect={() => setValue(framework.value)}
            >
              {framework.label}
            </CommandItem>
          ))}
        </CommandGroup>
      </CommandList>
    </Command>
  </PopoverContent>
</Popover>

Common Patterns

Loading Button

import { Loader2 } from "lucide-react"

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

Confirmation Dialog

<AlertDialog>
  <AlertDialogTrigger asChild>
    <Button variant="destructive">Delete</Button>
  </AlertDialogTrigger>
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogTitle>Are you sure?</AlertDialogTitle>
      <AlertDialogDescription>
        This action cannot be undone.
      </AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogCancel>Cancel</AlertDialogCancel>
      <AlertDialogAction onClick={handleDelete}>
        Delete
      </AlertDialogAction>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>

Search with Command

<Dialog>
  <DialogTrigger asChild>
    <Button variant="outline" className="w-[200px] justify-start">
      <Search className="mr-2 h-4 w-4" />
      Search...
      <Kbd className="ml-auto">⌘K</Kbd>
    </Button>
  </DialogTrigger>
  <DialogContent className="p-0">
    <Command>
      <CommandInput placeholder="Search..." />
      <CommandList>
        <CommandEmpty>No results.</CommandEmpty>
        <CommandGroup heading="Pages">
          <CommandItem>Dashboard</CommandItem>
          <CommandItem>Settings</CommandItem>
        </CommandGroup>
      </CommandList>
    </Command>
  </DialogContent>
</Dialog>

Responsive Mobile Menu

// Desktop: Navigation Menu
// Mobile: Sheet with menu

<div className="hidden md:block">
  <NavigationMenu>{/* desktop nav */}</NavigationMenu>
</div>

<div className="md:hidden">
  <Sheet>
    <SheetTrigger asChild>
      <Button variant="ghost" size="icon">
        <Menu />
      </Button>
    </SheetTrigger>
    <SheetContent side="left">
      {/* mobile nav links */}
    </SheetContent>
  </Sheet>
</div>

Theming

CSS Variables (globals.css)

@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 240 10% 3.9%;
    --primary: 240 5.9% 10%;
    --primary-foreground: 0 0% 98%;
    --secondary: 240 4.8% 95.9%;
    --secondary-foreground: 240 5.9% 10%;
    --muted: 240 4.8% 95.9%;
    --muted-foreground: 240 3.8% 46.1%;
    --accent: 240 4.8% 95.9%;
    --accent-foreground: 240 5.9% 10%;
    --destructive: 0 84.2% 60.2%;
    --destructive-foreground: 0 0% 98%;
    --border: 240 5.9% 90%;
    --input: 240 5.9% 90%;
    --ring: 240 5.9% 10%;
    --radius: 0.5rem;
  }

  .dark {
    --background: 240 10% 3.9%;
    --foreground: 0 0% 98%;
    /* ... dark mode values */
  }
}

Using Theme Colors

// In Tailwind classes
<div className="bg-background text-foreground" />
<div className="bg-primary text-primary-foreground" />
<div className="bg-muted text-muted-foreground" />
<div className="border-border" />

Component Customization

Extending Variants (CVA)

// components/ui/button.tsx
import { cva } 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",
        outline: "border border-input bg-background hover:bg-accent",
        secondary: "bg-secondary text-secondary-foreground",
        ghost: "hover:bg-accent hover:text-accent-foreground",
        link: "text-primary underline-offset-4 hover:underline",
        // Add custom variants
        success: "bg-green-600 text-white hover:bg-green-700",
        warning: "bg-yellow-500 text-black hover:bg-yellow-600",
      },
      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",
        // Add custom sizes
        xl: "h-14 rounded-lg px-10 text-lg",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  }
)

Decision Guide

Need a component?
       │
       ▼
┌──────────────────────────┐
│ Is it a STANDARD UI      │
│ element? (button, input, │
│ modal, table, form...)   │
└──────────────────────────┘
       │
  YES ─┴─ NO
   │       │
   ▼       ▼
shadcn   Check Aceternity
 /ui     or Magic UI

Troubleshooting

"Component not found":
  → npx shadcn@latest add [component] --overwrite
  → Check components.json exists

"Styles not applying":
  → Check tailwind.config.ts content paths
  → Check globals.css has CSS variables

"Hydration mismatch (Dialog/Sheet)":
  → Add suppressHydrationWarning to <html>
  → Use dynamic(() => import(...), { ssr: false })

"Dark mode not working":
  → npm install next-themes
  → Add darkMode: ['class'] to tailwind.config.ts
  → Wrap app with ThemeProvider

"Form errors not showing":
  → Include <FormMessage /> in FormField
  → Check zodResolver(schema) is set

References

patterns.md — Dark mode toggle, multi-step forms, data tables, file upload

External Resources

https://ui.shadcn.com/docs — Documentation
https://ui.shadcn.com/docs/components — Components list
https://ui.shadcn.com/themes — Theme generator
https://ui.shadcn.com/blocks — Example blocks

frontend-shadcn

Install Skill

SKILL.md