1---
2name: shadcn-ui
3description: Provides complete shadcn/ui component library patterns including installation, configuration, and implementation of accessible React components. Use when setting up shadcn/ui, installing components, building forms with React Hook Form and Zod, customizing themes with Tailwind CSS, or implementing UI patterns like buttons, dialogs, dropdowns, tables, and complex form layouts.
4allowed-tools: Read, Write, Bash, Edit, Glob
5---
6 
7# shadcn/ui Component Patterns
8 
9Build accessible, customizable UI components with shadcn/ui, Radix UI, and Tailwind CSS.
10 
11## Overview
12 
13- Components are **copied into your project** — you own and customize the code
14- Built on **Radix UI** primitives for full accessibility
15- Styled with **Tailwind CSS** and CSS variables for theming
16- CLI-based installation: `npx shadcn@latest add <component>`
17 
18## When to Use
19 
20Activate when user requests involve:
21- "Set up shadcn/ui", "initialize shadcn", "add shadcn components"
22- "Install button/input/form/dialog/card/select/toast/table/chart"
23- "React Hook Form", "Zod validation", "form with validation"
24- "accessible components", "Radix UI", "Tailwind theme"
25- "shadcn button", "shadcn dialog", "shadcn sheet", "shadcn table"
26- "dark mode", "CSS variables", "custom theme"
27- "charts with Recharts", "bar chart", "line chart", "pie chart"
28 
29## Quick Reference
30 
31### Available Components
32 
33| Component | Install Command | Description |
34|-----------|----------------|-------------|
35| `button` | `npx shadcn@latest add button` | Variants: default, destructive, outline, secondary, ghost, link |
36| `input` | `npx shadcn@latest add input` | Text input field |
37| `form` | `npx shadcn@latest add form` | React Hook Form integration with validation |
38| `card` | `npx shadcn@latest add card` | Container with header, content, footer |
39| `dialog` | `npx shadcn@latest add dialog` | Modal overlay |
40| `sheet` | `npx shadcn@latest add sheet` | Slide-over panel (top/right/bottom/left) |
41| `select` | `npx shadcn@latest add select` | Dropdown select |
42| `toast` | `npx shadcn@latest add toast` | Notification toasts |
43| `table` | `npx shadcn@latest add table` | Data table |
44| `menubar` | `npx shadcn@latest add menubar` | Desktop-style menubar |
45| `chart` | `npx shadcn@latest add chart` | Recharts wrapper with theming |
46| `textarea` | `npx shadcn@latest add textarea` | Multi-line text input |
47| `checkbox` | `npx shadcn@latest add checkbox` | Checkbox input |
48| `label` | `npx shadcn@latest add label` | Accessible form label |
49 
50## Instructions
51 
52### Initialize Project
53 
54```bash
55# New Next.js project
56npx create-next-app@latest my-app --typescript --tailwind --eslint --app
57cd my-app
58npx shadcn@latest init
59 
60# Existing project
61npm install tailwindcss-animate class-variance-authority clsx tailwind-merge lucide-react
62npx shadcn@latest init
63 
64# Install components
65npx shadcn@latest add button input form card dialog select toast
66```
67 
68### Basic Component Usage
69 
70```tsx
71// Button with variants and sizes
72import { Button } from "@/components/ui/button"
73 
74<Button variant="default">Default</Button>
75<Button variant="destructive" size="sm">Delete</Button>
76<Button variant="outline" disabled>Loading...</Button>
77```
78 
79### Form with Zod Validation
80 
81```tsx
82"use client"
83 
84import { zodResolver } from "@hookform/resolvers/zod"
85import { useForm } from "react-hook-form"
86import { z } from "zod"
87import { Button } from "@/components/ui/button"
88import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from "@/components/ui/form"
89import { Input } from "@/components/ui/input"
90 
91const formSchema = z.object({
92  email: z.string().email("Invalid email"),
93  password: z.string().min(8, "Password must be at least 8 characters"),
94})
95 
96export function LoginForm() {
97  const form = useForm<z.infer<typeof formSchema>>({
98    resolver: zodResolver(formSchema),
99    defaultValues: { email: "", password: "" },
100  })
101 
102  return (
103    <Form {...form}>
104      <form onSubmit={form.handleSubmit(console.log)} className="space-y-4">
105        <FormField name="email" control={form.control} render={({ field }) => (
106          <FormItem>
107            <FormLabel>Email</FormLabel>
108            <FormControl><Input type="email" {...field} /></FormControl>
109            <FormMessage />
110          </FormItem>
111        )} />
112        <FormField name="password" control={form.control} render={({ field }) => (
113          <FormItem>
114            <FormLabel>Password</FormLabel>
115            <FormControl><Input type="password" {...field} /></FormControl>
116            <FormMessage />
117          </FormItem>
118        )} />
119        <Button type="submit">Login</Button>
120      </form>
121    </Form>
122  )
123}
124```
125 
126See [references/forms-and-validation.md](references/forms-and-validation.md) for advanced multi-field forms, contact forms with API submission, and login card patterns.
127 
128### Dialog (Modal)
129 
130```tsx
131import { Button } from "@/components/ui/button"
132import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogTrigger } from "@/components/ui/dialog"
133 
134<Dialog>
135  <DialogTrigger asChild>
136    <Button variant="outline">Open</Button>
137  </DialogTrigger>
138  <DialogContent>
139    <DialogHeader>
140      <DialogTitle>Edit Profile</DialogTitle>
141    </DialogHeader>
142    {/* content */}
143  </DialogContent>
144</Dialog>
145```
146 
147### Toast Notification
148 
149```tsx
150// 1. Add <Toaster /> to app/layout.tsx
151import { Toaster } from "@/components/ui/toaster"
152 
153// 2. Use in components
154import { useToast } from "@/components/ui/use-toast"
155 
156const { toast } = useToast()
157toast({ title: "Success", description: "Changes saved." })
158toast({ variant: "destructive", title: "Error", description: "Something went wrong." })
159```
160 
161### Bar Chart
162 
163```tsx
164import { Bar, BarChart, CartesianGrid, XAxis } from "recharts"
165import { ChartContainer, ChartTooltipContent } from "@/components/ui/chart"
166 
167const chartConfig = {
168  desktop: { label: "Desktop", color: "var(--chart-1)" },
169} satisfies import("@/components/ui/chart").ChartConfig
170 
171<ChartContainer config={chartConfig} className="min-h-[200px] w-full">
172  <BarChart data={data}>
173    <CartesianGrid vertical={false} />
174    <XAxis dataKey="month" />
175    <Bar dataKey="desktop" fill="var(--color-desktop)" radius={4} />
176    <ChartTooltip content={<ChartTooltipContent />} />
177  </BarChart>
178</ChartContainer>
179```
180 
181See [references/charts-components.md](references/charts-components.md) for Line, Area, and Pie chart examples.
182 
183## Examples
184 
185### Login Form with Validation
186```tsx
187"use client"
188import { zodResolver } from "@hookform/resolvers/zod"
189import { useForm } from "react-hook-form"
190import { z } from "zod"
191import { Button } from "@/components/ui/button"
192import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from "@/components/ui/form"
193import { Input } from "@/components/ui/input"
194 
195const formSchema = z.object({
196  email: z.string().email("Invalid email"),
197  password: z.string().min(8, "Min 8 characters"),
198})
199 
200export function LoginForm() {
201  const form = useForm<z.infer<typeof formSchema>>({
202    resolver: zodResolver(formSchema),
203    defaultValues: { email: "", password: "" },
204  })
205 
206  return (
207    <Form {...form}>
208      <form onSubmit={form.handleSubmit(console.log)} className="space-y-4">
209        <FormField name="email" control={form.control} render={({ field }) => (
210          <FormItem>
211            <FormLabel>Email</FormLabel>
212            <FormControl><Input type="email" {...field} /></FormControl>
213            <FormMessage />
214          </FormItem>
215        )} />
216        <FormField name="password" control={form.control} render={({ field }) => (
217          <FormItem>
218            <FormLabel>Password</FormLabel>
219            <FormControl><Input type="password" {...field} /></FormControl>
220            <FormMessage />
221          </FormItem>
222        )} />
223        <Button type="submit">Login</Button>
224      </form>
225    </Form>
226  )
227}
228```
229 
230### Data Table with Actions
231```tsx
232import { ColumnDef } from "@tanstack/react-table"
233import { Button } from "@/components/ui/button"
234import { Checkbox } from "@/components/ui/checkbox"
235import { DataTable } from "@/components/ui/data-table"
236 
237const columns: ColumnDef<User>[] = [
238  { id: "select", header: ({ table }) => (
239    <Checkbox checked={table.getIsAllPageRowsSelected()} />
240  ), cell: ({ row }) => (
241    <Checkbox checked={row.getIsSelected()} />
242  )},
243  { accessorKey: "name", header: "Name" },
244  { accessorKey: "email", header: "Email" },
245  { id: "actions", cell: ({ row }) => (
246    <Button variant="ghost" size="sm">Edit</Button>
247  )},
248]
249```
250 
251### Dialog with Form
252```tsx
253import { Button } from "@/components/ui/button"
254import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogTrigger } from "@/components/ui/dialog"
255 
256<Dialog>
257  <DialogTrigger asChild>
258    <Button variant="outline">Add User</Button>
259  </DialogTrigger>
260  <DialogContent>
261    <DialogHeader>
262      <DialogTitle>Add New User</DialogTitle>
263    </DialogHeader>
264    {/* <LoginForm /> */}
265  </DialogContent>
266</Dialog>
267```
268 
269### Toast Notifications
270```tsx
271import { useToast } from "@/components/ui/use-toast"
272import { Button } from "@/components/ui/button"
273 
274const { toast } = useToast()
275 
276toast({ title: "Saved", description: "Changes saved successfully." })
277toast({ variant: "destructive", title: "Error", description: "Failed to save." })
278```
279 
280## Best Practices
281 
282- **Accessibility**: Use Radix UI primitives — ARIA attributes are built in
283- **Client Components**: Add `"use client"` for interactive components (hooks, events)
284- **Type Safety**: Use TypeScript and Zod schemas for form validation
285- **Theming**: Configure CSS variables in `globals.css` for consistent design
286- **Customization**: Modify component files directly — you own the code
287- **Path Aliases**: Ensure `@` alias is configured in `tsconfig.json`
288- **Registry Security**: Only install components from trusted registries; review generated code before production use
289- **Dark Mode**: Set up with CSS variables strategy and `next-themes`
290- **Forms**: Always use `Form`, `FormField`, `FormItem`, `FormLabel`, `FormMessage` together
291- **Toaster**: Add `<Toaster />` once to root layout
292 
293## Constraints and Warnings
294 
295- **Not an NPM Package**: Components are copied to your project; they are not a versioned dependency
296- **Registry Security**: Components from `npx shadcn@latest add` are fetched remotely; always verify the registry source is trusted before installation
297- **Client Components**: Most interactive components require `"use client"` directive
298- **Radix Dependencies**: Ensure all `@radix-ui` packages are installed
299- **Tailwind Required**: Components rely on Tailwind CSS utilities
300- **Path Aliases**: Configure `@` alias in `tsconfig.json` for imports
301 
302## References
303 
304Consult these files for detailed patterns and code examples:
305 
306- **[references/setup-and-configuration.md](references/setup-and-configuration.md)** — Full installation, tsconfig, tailwind config, CSS variables
307- **[references/ui-components.md](references/ui-components.md)** — Button, Input, Card, Dialog, Sheet, Select, Toast, Table, Menubar
308- **[references/forms-and-validation.md](references/forms-and-validation.md)** — React Hook Form + Zod, advanced forms, login card, contact form
309- **[references/charts-components.md](references/charts-components.md)** — Bar, Line, Area, Pie charts with ChartContainer and theming
310- **[references/nextjs-integration.md](references/nextjs-integration.md)** — App Router, Server/Client Components, dark mode, metadata
311- **[references/customization.md](references/customization.md)** — Custom variants, CSS variables, cn() utility, extending components
312