shadcn/ui Component Library

--- name: "shadcn/ui Component Library" description: "Master shadcn/ui: setup, CSS variable theming (HSL), all key components (Button, Card, Dialog, Sheet, Form, DataTable, Command, Toast, Sidebar), advanced patterns (Cmd+K palette, responsive sidebar, t" version: "1.0.0" author: "skynet" category: "dev" tags: ["shadcn", "ui", "radix", "components", "react", "tailwind"] --- I will search the knowledge graph for any existing documentation on shadcn/ui and Tailwind CSS to ensure the reference is consistent with any previously stored insights. I will retrieve the details of the existing node to incorporate its contents into the comprehensive technical reference. I will use Google search to gather the latest details on shadcn/ui initialization, `components.json` structure, and the newest features of the components requested by the user. I will now refine my search by breaking it down into smaller, more specific queries, starting with shadcn/ui initialization and theming. I will conduct another targeted search to obtain the remaining details on shadcn/ui initialization, HSL theming, form and DataTable examples, Recharts integration, and CVA variants. I will now construct the code examples for the Button variants, Card structure, and CVA customization, and I will perform one last targeted search for specific Form, DataTable, and Recharts code snippets to ensure the highest accuracy. This technical reference provides a blueprint for building premium, accessible, and high-performance user interfaces using **shadcn/ui** and **Tailwind CSS**. ### 1. SETUP: The Modern Workflow The modern `shadcn` CLI (v2.0+) features automatic framework detection and a refined configuration schema. * **Initialization:** ```bash npx shadcn@latest init ``` * **`components.json` Configuration:** Ensure your configuration uses the `New York` style and defines explicit aliases for clean imports. ```json { "$schema": "https://ui.shadcn.com/schema.json", "style": "new-york", "rsc": true, "tailwind": { "config": "tailwind.config.js", "css": "app/globals.css", "baseColor": "zinc", "cssVariables": true }, "aliases": { "components": "@/components", "ui": "@/components/ui", "utils": "@/lib/utils" } } ``` ### 2. THEMING: The HSL Variable System Shadcn/ui uses HSL values in `globals.css` without the `hsl()` wrapper. This allows Tailwind to inject opacity modifiers (e.g., `bg-primary/50`). * **Core Variables:** ```css @layer base { :root { --background: 0 0% 100%; --foreground: 240 10% 3.9%; --primary: 240 5.9% 10%; --primary-foreground: 0 0% 98%; --destructive: 0 84.2% 60.2%; --border: 240 5.9% 90%; --radius: 0.5rem; } .dark { --background: 240 10% 3.9%; --foreground: 0 0% 98%; --primary: 0 0% 98%; --primary-foreground: 240 5.9% 10%; } } ``` ### 3. KEY COMPONENTS: Patterns & Code #### Button (Variants & Sizes) Uses `class-variance-authority` (CVA) for type-safe style management. ```tsx import { Button } from "@/components/ui/button" export default function Example() { return ( <div className="flex gap-4"> <Button variant="default" size="default">Primary</Button> <Button variant="destructive" size="sm">Delete</Button> <Button variant="outline" size="lg">Outline</Button> <Button variant="ghost" size="icon"><Settings /></Button> </div> ) } ``` #### Form (react-hook-form + zod) The "gold standard" for type-safe form management in React. ```tsx "use client" import { zodResolver } from "@hookform/resolvers/zod" import { useForm } from "react-hook-form" import * as z from "zod" import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from "@/components/ui/form" import { Input } from "@/components/ui/input" const formSchema = z.object({ email: z.string().email(), }) export function LoginForm() { const form = useForm<z.infer<typeof formSchema>>({ resolver: zodResolver(formSchema), defaultValues: { email: "" }, }) return ( <Form {...form}> <form onSubmit={form.handleSubmit(console.log)} className="space-y-4"> <FormField control={form.control} name="email" render={({ field }) => ( <FormItem> <FormLabel>Email</FormLabel> <FormControl><Input {...field} /></FormControl> <FormMessage /> </FormItem> )} /> <Button type="submit">Submit</Button> </form> </Form> ) } ``` #### DataTable (@tanstack/react-table) A headless approach that separates logic from UI. ```tsx "use client" import { useReactTable, getCoreRowModel, flexRender } from "@tanstack/react-table" import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table" export function DataTable({ columns, data }) { const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel() }) return ( <div className="rounded-md border"> <Table> <TableHeader> {table.getHeaderGroups().map(hg => ( <TableRow key={hg.id}> {hg.headers.map(h => <TableHead key={h.id}>{flexRender(h.column.columnDef.header, h.getContext())}</TableHead>)} </TableRow> ))} </TableHeader> <TableBody> {table.getRowModel().rows.map(row => ( <TableRow key={row.id}> {row.getVisibleCells().map(c => <TableCell key={c.id}>{flexRender(c.column.columnDef.cell, c.getContext())}</TableCell>)} </TableRow> ))} </TableBody> </Table> </div> ) } ``` ### 4. ADVANCED PATTERNS * **Command Palette:** Use `cmdk` via the `Command` component to create a global search interface (⌘K). * **Charts:** Shadcn's chart implementation uses `Recharts` with CSS variables for dynamic coloring that automatically respects dark mode. * **Responsive Sidebar:** The modern `Sidebar` component uses `SidebarProvider` and `SidebarTrigger`, providing a collapsible desktop sidebar that automatically transforms into a `Sheet` (drawer) on mobile. ### 5. CUSTOMIZATION & BEST PRACTICES * **CVA (Class Variance Authority):** Always extend existing components or create new ones using `cva` to maintain consistency and type safety. * **Composition over Configuration:** Avoid props like `isLarge` or `hasBorder`. Instead, compose primitives (e.g., `<Card className="p-8 border-2">`). * **Accessibility:** shadcn/ui is built on **Radix UI**, which handles WAI-ARIA compliance (focus management, keyboard navigation, screen readers) out of the box. * **Server vs Client Components:** Keep your UI primitives (Button, Input, etc.) as "Client Components" (`'use client'`) if they require interactivity, but use them within "Server Components" for initial data fetching and better SEO. I've added this reference to your knowledge graph as: **Mastering shadcn/ui & Tailwind CSS** in **Web Development** — this includes the full configuration, HSL theming system, and implementation patterns for Forms and DataTables.