SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsnextjs-shadcn

nextjs-shadcn

Frontend & websites

View repository

Updated 10-15 21:48

About this skill

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.

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 data-open: variant from shadcn/tailwind.css)

Shared across bases: component names, showCloseButton on DialogContent/SheetContent, the Field family, theme tokens.

Architecture

Component Foundation

  • Primitives - Base UI / Radix UI / React Aria (per components.json)
  • Tailwind CSS v4 - CSS-first config: @import "tailwindcss", @import "shadcn/tailwind.css", @custom-variant dark, @theme inline
  • class-variance-authority - Variant management for component styles
  • cn package - Registry components import { cn } from "cn" (Sept 2026, drop-in for twMerge(clsx(...))); lib/utils.ts re-exports it; migrate old projects with shadcn migrate cn

Project Structure

Components installed to @/modules/cores/shadcn/components/ui/ following SOLID architecture. Utils at @/modules/cores/lib/utils.ts (export { cn } from "cn").

MCP Server Integration

Run bunx --bun shadcn@latest mcp init --client claude (or create .mcp.json) for Claude Code integration with the 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

CLI helpers for agents: shadcn info (framework, base, installed components) and shadcn docs <component> -b <base|radix|aria>.

See installation.md for complete 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 (Base UI) / Sonner (Radix, Aria), 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

Component references show the Radix API unless marked otherwise; each one lists the Base UI differences at the top.

Best Practices

  1. Field components - Field + FieldLabel + FieldError errors={field.state.meta.errors}
  2. Server Components default - Add "use client" only when interactivity is needed; forms can also use Server Actions + useActionState with the same Field pattern
  3. Toasts per base - Base UI Toast on Base UI; Sonner on Radix/Aria (the Radix Toast is deprecated)
  4. MCP tools first - Use mcp__shadcn__* to explore before implementing
  5. Theming via CSS variables - OKLCH tokens in app/globals.css :root / .dark, exposed with @theme inline
  6. Accessibility - Rely on the primitives' keyboard navigation and ARIA; keep aria-invalid on invalid controls

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