| name | nextjs-shadcn |
| description | shadcn/ui for Next.js App Router with TanStack Form. Use when building UI components, forms, dialogs, tables, toasts, or accessible components. Use when this capability is needed. |
| metadata | {"author":"fusengine"} |
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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
