shadcn/ui for Next.js
Beautiful, accessible components built on Radix UI with Tailwind CSS styling.
Agent Workflow (MANDATORY)
Before ANY implementation, use TeamCreate to spawn 3 agents:
- fuse-ai-pilot:explore-codebase - Analyze existing components and patterns
- fuse-ai-pilot:research-expert - Verify latest shadcn/ui docs via Context7/Exa
- mcp__shadcn__* - Search registry for component availability
After implementation, run fuse-ai-pilot:sniper for validation.
Overview
When to Use
- Building UI components for Next.js App Router applications
- Need accessible, customizable form components (inputs, selects, checkboxes)
- Implementing dialogs, sheets, drawers, or overlay patterns
- Creating data tables with sorting, filtering, and pagination
- Building navigation menus, sidebars, or command palettes
- Need toast notifications or alert feedback components
Why shadcn/ui
| Feature | Benefit |
|---|---|
| Copy/paste model | Components copied to your project, full ownership |
| Radix UI foundation | Accessibility built-in, unstyled primitives |
| Tailwind CSS styling | Utility-first, easy customization |
| TanStack Form ready | Modern form library with Field pattern |
| Server Components | RSC-compatible, optimal bundle size |
| Lucide icons | Consistent, customizable icon set |
Critical Rules
- NEVER create components manually - Always install with
bunx --bun shadcn@latest add - TanStack Form only - NOT React Hook Form for all form implementations
- Radix UI primitives - Components built on Radix (NOT Base UI)
- Lucide icons - Default icon library, NOT Remix icons or others
- Field pattern - Use Field, FieldLabel, FieldError for form fields
- SOLID paths - Components at
@/modules/cores/shadcn/components/ui/
Architecture
Component Foundation
- Radix UI - Headless, accessible primitives (Dialog, Select, Popover, Tabs)
- Tailwind CSS v4 - Styling via utility classes, CSS-first config
- class-variance-authority - Variant management for component styles
- clsx + tailwind-merge - Conditional class composition via
cn()utility
Project Structure
Components installed to @/modules/cores/shadcn/components/ui/ following SOLID architecture. Utils at @/modules/cores/lib/utils.ts with cn() helper function.
MCP Server Integration
Create .mcp.json at project root for Claude Code integration with shadcn registry.
Available MCP Tools
mcp__shadcn__search_items_in_registries- Search available componentsmcp__shadcn__view_items_in_registries- View component source codemcp__shadcn__get_item_examples_from_registries- Get usage examplesmcp__shadcn__get_add_command_for_items- Get installation commands
See installation.md for complete MCP setup.
Component Categories
| Category | Components | Primary Reference |
|---|---|---|
| Setup | Init, configuration, theming, icons | installation.md |
| Forms | Button, Input, Field, Select, Checkbox, Switch, Slider | field-patterns.md |
| Overlay | Dialog, Sheet, Drawer, Popover, Tooltip, HoverCard | dialog.md |
| Feedback | Alert, Toast (Sonner), Progress, Skeleton, Spinner | toast.md |
| Data Display | Table, Badge, Avatar, Calendar, Chart, Carousel | table.md |
| Navigation | Breadcrumb, DropdownMenu, Command, Sidebar, Tabs | sidebar.md |
| Layout | Card, Accordion, Separator, ScrollArea, Resizable | card.md |
Best Practices
- Field components - Use new Field pattern for consistent form field structure
- Server Components default - Add
'use client'only when interactivity needed - Sonner for toasts - Modern toast notifications over legacy toast
- MCP tools first - Use
mcp__shadcn__*to explore before implementing - Theming via CSS variables - Customize colors in
globals.css:root - Accessibility - Rely on Radix UI keyboard navigation and ARIA
Reference Guide
| Need | Reference |
|---|---|
| Initial setup | installation.md, configuration.md |
| Form patterns | field-patterns.md, form-examples.md |
| Theme customization | theming.md |
| Data tables | table.md |
| Modal dialogs | dialog.md, alert-dialog.md |
| Navigation | sidebar.md, navigation-menu.md |