Nextjs Shadcn

---
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.
versions:
  shadcn-ui: 3.8.0
  nextjs: 16
  tailwindcss: 4
user-invocable: true
references: references/installation.md, references/configuration.md, references/theming.md, references/button.md, references/input.md, references/label.md, references/textarea.md, references/card.md, references/select.md, references/checkbox.md, references/switch.md, references/radio-group.md, references/slider.md, references/toggle.md, references/toggle-group.md, references/input-otp.md, references/dialog.md, references/alert-dialog.md, references/sheet.md, references/drawer.md, references/popover.md, references/tooltip.md, references/hover-card.md, references/context-menu.md, references/collapsible.md, references/toast.md, references/alert.md, references/skeleton.md, references/progress.md, references/spinner.md, references/table.md, references/tabs.md, references/accordion.md, references/badge.md, references/avatar.md, references/separator.md, references/scroll-area.md, references/aspect-ratio.md, references/resizable.md, references/carousel.md, references/chart.md, references/dropdown.md, references/command.md, references/breadcrumb.md, references/navigation-menu.md, references/menubar.md, references/sidebar.md, references/pagination.md, references/calendar.md, references/field-patterns.md, references/form-examples.md
related-skills: nextjs-16, nextjs-tanstack-form, tailwindcss, solid-nextjs
---

# 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:

1. **fuse-ai-pilot:explore-codebase** - Analyze existing components and patterns
2. **fuse-ai-pilot:research-expert** - Verify latest shadcn/ui docs via Context7/Exa
3. **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

1. **NEVER create components manually** - Always install with `bunx --bun shadcn@latest add`
2. **TanStack Form only** - NOT React Hook Form for all form implementations
3. **Radix UI primitives** - Components built on Radix (NOT Base UI)
4. **Lucide icons** - Default icon library, NOT Remix icons or others
5. **Field pattern** - Use Field, FieldLabel, FieldError for form fields
6. **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](references/installation.md) for complete MCP setup.

---

## Component Categories

| Category | Components | Primary Reference |
|----------|------------|-------------------|
| Setup | Init, configuration, theming, icons | [installation.md](references/installation.md) |
| Forms | Button, Input, Field, Select, Checkbox, Switch, Slider | [field-patterns.md](references/field-patterns.md) |
| Overlay | Dialog, Sheet, Drawer, Popover, Tooltip, HoverCard | [dialog.md](references/dialog.md) |
| Feedback | Alert, Toast (Sonner), Progress, Skeleton, Spinner | [toast.md](references/toast.md) |
| Data Display | Table, Badge, Avatar, Calendar, Chart, Carousel | [table.md](references/table.md) |
| Navigation | Breadcrumb, DropdownMenu, Command, Sidebar, Tabs | [sidebar.md](references/sidebar.md) |
| Layout | Card, Accordion, Separator, ScrollArea, Resizable | [card.md](references/card.md) |

---

## Best Practices

1. **Field components** - Use new Field pattern for consistent form field structure
2. **Server Components default** - Add `'use client'` only when interactivity needed
3. **Sonner for toasts** - Modern toast notifications over legacy toast
4. **MCP tools first** - Use `mcp__shadcn__*` to explore before implementing
5. **Theming via CSS variables** - Customize colors in `globals.css` `:root`
6. **Accessibility** - Rely on Radix UI keyboard navigation and ARIA

---

## Reference Guide

| Need | Reference |
|------|-----------|
| Initial setup | [installation.md](references/installation.md), [configuration.md](references/configuration.md) |
| Form patterns | [field-patterns.md](references/field-patterns.md), [form-examples.md](references/form-examples.md) |
| Theme customization | [theming.md](references/theming.md) |
| Data tables | [table.md](references/table.md) |
| Modal dialogs | [dialog.md](references/dialog.md), [alert-dialog.md](references/alert-dialog.md) |
| Navigation | [sidebar.md](references/sidebar.md), [navigation-menu.md](references/navigation-menu.md) |