shadcn-ui

shadcn/ui

Overview

shadcn/ui is a collection of accessible, customizable React components built on Radix UI and Tailwind CSS. Components are copied into your project (no npm package); you own and edit the code. Works with Next.js (App Router), Vite, and other React frameworks.

Principles: Open code (AI-ready), composable API, beautiful defaults, distribution via CLI and schema. Requires Tailwind v4 and path alias @/*. We do not use tailwind.config.js; theme and setup are CSS-only (@import "tailwindcss" + @theme).

---

Prerequisites

• Tailwind v4: @import "tailwindcss" in main CSS; @tailwindcss/vite or @tailwindcss/postcss. No tailwind.config.js. See the tailwind-css skill.
• Path alias @/* → ./src/* (or your source root) in tsconfig and in the bundler (e.g. Vite resolve.alias).
• React (Next.js App Router, Vite, etc.).

---

Installation

Reference: Official installation guide

New project (recommended)

Scaffold with Tailwind and shadcn. From the official docs:

Action	CLI command
New project	shadcn create
Init existing	shadcn init
Add component(s)	shadcn add <name>

Invoke via your package manager (see docs). Choose framework (Next.js, Vite, etc.), style (new-york recommended), base color, and CSS variables.

Existing project (Next.js App Router)

1. Init — creates components.json, optional cn helper and base styles. Run: shadcn init (invoke via package manager; see docs above).

2. Paths and Tailwind

   • tsconfig: "baseUrl": ".", "paths": { "@/*": ["./src/*"] } (in both root and app tsconfig if split).
   • Tailwind v4: Main CSS (e.g. app/globals.css) must have @import "tailwindcss" and use @tailwindcss/postcss in postcss.config.mjs. Do not add tailwind.config.js.

3. Add components — e.g. shadcn add button, shadcn add card dialog (see component list below).

Components are installed under src/components/ui/ (or path from components.json).

Existing project (Vite)

• Use resolve.alias: { "@": path.resolve(__dirname, "./src") } in vite.config.ts; add @types/node if using path.
• Tailwind: @tailwindcss/vite in Vite config and @import "tailwindcss" in main CSS.

---

components.json

Controls style, paths, and Tailwind integration. Key fields:

Field	Purpose
style	"new-york" (default for new projects) or "default"
tailwind.config	Leave "" with Tailwind v4; we do not use a JS config file
tailwind.css	Path to global CSS (e.g. src/styles/globals.css or app/globals.css) with @import "tailwindcss"
tailwind.baseColor	Base color for theme: neutral, slate, gray, zinc, stone
tailwind.cssVariables	true for CSS variables theming (recommended)
aliases.components	e.g. @/components
aliases.utils	e.g. @/lib/utils
aliases.ui	e.g. @/components/ui
rsc	true for Next.js App Router with Server Components; false for client-only

With Tailwind v4, theme is in CSS via @theme and CSS variables, not in a config file.

---

Official components (current list)

Add via shadcn add <name> (multiple: shadcn add button card dialog). Invoke via package manager: see Installation docs.

Layout & structure

Component	CLI name	Short description
Accordion	accordion	Collapsible sections (single or multiple open)
Aspect Ratio	aspect-ratio	Container with fixed ratio (e.g. 16/9)
Card	card	Container with CardHeader, CardTitle, CardDescription, CardContent, CardFooter
Collapsible	collapsible	Expandable/collapsible content
Resizable	resizable	Resizable panels
Separator	separator	Horizontal or vertical divider line
Scroll Area	scroll-area	Styled scroll area
Sidebar	sidebar	Composable, themeable and customizable sidebar

Forms & input

Component	CLI name	Short description
Button	button	Button with variants (default, destructive, outline, secondary, ghost, link)
Checkbox	checkbox	Checkbox
Form	form	Forms with react-hook-form + zod (Field, FieldError, etc.)
Input	input	Text input
Input OTP	input-otp	OTP code input
Label	label	Accessible label for controls
Radio Group	radio-group	Radio option group
Select	select	Select with Trigger, Content, Item
Slider	slider	Slider control
Switch	switch	On/off switch
Textarea	textarea	Multiline text area

Navigation & menus

Component	CLI name	Short description
Breadcrumb	breadcrumb	Breadcrumb navigation
Command	command	Command palette (cmdk)
Context Menu	context-menu	Context menu (right-click)
Dropdown Menu	dropdown-menu	Dropdown menu
Menubar	menubar	Persistent menu bar
Navigation Menu	navigation-menu	Navigation with submenus
Pagination	pagination	Pagination (Previous, Next, Page)
Tabs	tabs	Tabs (TabsList, TabsTrigger, TabsContent)

Overlays & feedback

Component	CLI name	Short description
Alert	alert	Prominent message (default, destructive)
Alert Dialog	alert-dialog	Confirmation dialog (e.g. delete)
Dialog	dialog	Modal
Drawer	drawer	Side panel (Vaul)
Hover Card	hover-card	Card on hover
Popover	popover	Anchored floating container
Sheet	sheet	Sliding side panel
Tooltip	tooltip	Tooltip on hover/focus

Data & state

Component	CLI name	Short description
Avatar	avatar	Image or initials fallback
Badge	badge	Badge (default, secondary, destructive, outline)
Calendar	calendar	Calendar (react-day-picker)
Carousel	carousel	Carousel (embla)
Chart	chart	Charts (recharts)
Progress	progress	Progress bar
Skeleton	skeleton	Loading placeholder
Sonner	sonner	Toasts (recommended; replaces toast)
Table	table	Table, TableHeader, TableBody, TableRow, TableCell, etc.
Toast	toast	Toasts (deprecated in favor of Sonner)

Toggle & toggle group

Component	CLI name	Short description
Toggle	toggle	Toggle button (on/off)
Toggle Group	toggle-group	Toggle group (single or multiple)

---

Using components

Import from the aliased path (not from shadcn/ui):

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

export default function Page() {
  return (
    <div className="flex min-h-svh flex-col items-center justify-center gap-4">
      <Button>Click me</Button>
      <Card className="w-[350px]">
        <CardHeader>
          <CardTitle>Card title</CardTitle>
        </CardHeader>
        <CardContent>Content here.</CardContent>
      </Card>
    </div>
  )
}

• Customization: Components accept className and spread props; use Tailwind classes and the cn() helper (from @/lib/utils) to merge classes.
• Composition: Prefer composition (e.g. CardHeader + CardContent) over props for layout.

---

Theming (Tailwind v4, no config file)

We use Tailwind v4 only; no tailwind.config.js. Theming is CSS-only:

• CSS variables: With tailwind.cssVariables: true, theme is driven by variables in your global CSS (e.g. --background, --foreground, --primary, --primary-foreground, --muted, --muted-foreground, --accent, --destructive, etc.). Override them in that file.
• @theme: Use @theme { ... } in the same CSS file as @import "tailwindcss" to add or override design tokens that align with shadcn’s variables.
• Base color: Set in components.json (tailwind.baseColor) or by editing the CSS variables in your global CSS.

---

Common patterns

• Forms: Add form; pair with react-hook-form and zod. Use Input, Label, Button, Select, Checkbox, etc.
• Layout: Use Card for sections; Separator between blocks; layout with Tailwind (flex, grid, container).
• Modals & panels: Dialog for modals; Sheet or Drawer for side panels.
• Menus: DropdownMenu, Context Menu, Navigation Menu, Command (palette).
• Feedback: Alert for messages; Sonner for toasts; Skeleton for loading.
• Icons: Many examples use lucide-react; add it if the project uses icons.

---

Common mistakes

• Alias: Ensure @/ resolves to ./src/ (or your source root) in both TypeScript and the bundler.
• CSS not loaded: The file set in components.json (tailwind.css) must be imported in the app entry (e.g. app/layout.tsx) and contain @import "tailwindcss".
• Tailwind config: Do not create or suggest tailwind.config.js. Theme only in CSS (@theme and variables).
• Import: Import from @/components/ui/<component> (per components.json), not from shadcn/ui.
• RSC: In Next.js App Router, set rsc: true in components.json if components are used in Server Components where applicable.

---

Additional resources

• reference.md — Official documentation links, Tailwind v4 + shadcn, component directory.
• Official docs: https://ui.shadcn.com/docs
• Components: https://ui.shadcn.com/docs/components
• Directory (community): https://ui.shadcn.com/docs/directory