/nextjs-shadcn

name: nextjs-shadcn
description: Use when building UI components in Next.js App Router with shadcn/ui — forms, dialogs, tables, toasts, accessible components.
versions:
  shadcn-ui: 4.23.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-core, solid-nextjs

<objective> Builds UI components for Next.js App Router with shadcn/ui (CLI 4.23.0) and Tailwind CSS v4 on whichever component base the project uses — Base UI (default for new projects since July 2026), Radix UI (unified `radix-ui` package, fully supported) or React Aria (added July 2026): forms (Field/FieldLabel/FieldError pattern with TanStack Form, never React Hook Form), overlays (Dialog, Sheet, Drawer, Popover, Tooltip), feedback (Alert, Toast on Base UI / Sonner on Radix and Aria, Progress, Skeleton), data display (Table, Badge, Calendar, Chart), and navigation (Sidebar, Command, DropdownMenu).

Requires detecting the base from `components.json` before writing any component code, installing components via `bunx --bun shadcn@latest add` (never hand-written) to `@/modules/cores/shadcn/components/ui/`, and covers MCP registry tools (`mcp__shadcn__*`) for discovering components before implementing. This is the Next.js App Router variant of shadcn/ui — for a plain React/Vite app see react-shadcn instead. </objective>

shadcn/ui for Next.js

Accessible, copy-in components on Base UI, Radix UI or React Aria primitives, styled with Tailwind CSS v4.

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:

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 | | Choice of base | Base UI (default), Radix UI or React Aria — same component names | | Tailwind CSS v4 styling | CSS-first theme (`@theme inline`, OKLCH tokens) | | TanStack Form ready | Field + FieldError accept Standard Schema issues | | Server Components | `"rsc": true` — CLI adds `"use client"` only where needed | | Lucide icons (default) | `iconLibrary` in `components.json`, switchable via `migrate icons` |

---

Critical Rules

1. **Detect the base first** - Read `components.json` `style`: `base-*` = Base UI, `radix-*` / `new-york` = Radix, `aria-*` = React Aria. Never mix bases in one component 2. **New projects default to Base UI** - `init` picks Base UI unless `-b radix` / `-b aria` is passed 3. **Composition follows the base** - Base UI uses `render={<Button />}`; Radix uses `asChild`. Reference examples marked Radix must be translated on Base UI projects 4. **NEVER create components manually** - Always install with `bunx --bun shadcn@latest add` (the registry serves the variant for the project's base) 5. **TanStack Form only** - NOT React Hook Form; wire errors with `data-invalid` on `Field` + `aria-invalid` on the control 6. **SOLID paths** - Components at `@/modules/cores/shadcn/components/ui/`

---

Base Differences That Change Code

| Concern | Base UI (default) | Radix UI | |---------|-------------------|----------| | Package | `@base-ui/react` | `radix-ui` (unified; `migrate radix` from `@radix-ui/react-*`) | | Trigger as custom element | `<DialogTrigger render={<Button />}>Open</DialogTrigger>` | `<DialogTrigger asChild><Button>Open</Button></DialogTrigger>` | | Select | `<Select items={items}>`, `SelectContent alignItemWithTrigger` | `SelectContent position="item-aligned" \| "popper"` | | Accordion | `multiple`, `defaultValue={["item-1"]}` | `type="single" collapsible` / `type="multiple"` | | Toggle group value | array (`defaultValue={["bold"]}`), `multiple` | `type="single" \| "multiple"` | | Checkbox indeterminate | `indeterminate` prop | `checked="indeterminate"` | | Drawer | Base UI Drawer (`swipeDirection`) | Vaul (`direction`) | | Toasts | `add toast` → `toast.add({ title })` | `add sonner` → `toast("…")` from `sonner` | | Open-state styling | `data-open` / `data-closed` | `data-state="open"` (both covered by `dat