shadcn/ui for React
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 React applications (Vite, CRA)
- •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 |
| 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 components - •
mcp__shadcn__view_items_in_registries- View component source code - •
mcp__shadcn__get_item_examples_from_registries- Get usage examples - •
mcp__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
- •Client Components - React apps are client-side by default
- •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
index.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 |