nextjs-shadcn

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

shadcn/ui for Next.js

适用于Next.js的shadcn/ui

Beautiful, accessible components built on Radix UI with Tailwind CSS styling.

基于Radix UI构建、采用Tailwind CSS样式的美观且具备可访问性的组件库。

Agent Workflow (MANDATORY)

Agent工作流（强制要求）

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.

在进行任何实现之前，使用

TeamCreate

生成3个Agent：

fuse-ai-pilot:explore-codebase - 分析现有组件和模式
fuse-ai-pilot:research-expert - 通过Context7/Exa验证最新的shadcn/ui文档
mcp__shadcn__* - 在注册表中搜索组件可用性

实现完成后，运行fuse-ai-pilot:sniper进行验证。

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

为Next.js App Router应用构建UI组件
需要具备可访问性、可自定义的表单组件（输入框、选择器、复选框）
实现对话框、侧边栏、抽屉或覆盖层模式
创建带有排序、筛选和分页功能的数据表格
构建导航菜单、侧边栏或命令面板
需要提示通知或告警反馈组件

Why shadcn/ui

选择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

特性	优势
复制粘贴模式	组件可复制到你的项目中，完全拥有所有权
Radix UI基础	内置可访问性，无样式基础组件
Tailwind CSS样式	实用优先，易于自定义
兼容TanStack Form	支持Field模式的现代表单库
服务端组件兼容	兼容RSC，优化包体积
Lucide图标	风格统一、可自定义的图标集

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/
```

禁止手动创建组件 - 始终使用
```
bunx --bun shadcn@latest add
```
命令安装
仅使用TanStack Form - 所有表单实现均使用TanStack Form，而非React Hook Form
基于Radix UI基础组件 - 组件需基于Radix构建（而非Base UI）
使用Lucide图标 - 默认图标库为Lucide，而非Remix icons或其他库
Field模式 - 表单字段使用Field、FieldLabel、FieldError组件
固定路径 - 组件存放于
```
@/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

Radix UI - 无样式、具备可访问性的基础组件（Dialog、Select、Popover、Tabs）
Tailwind CSS v4 - 通过工具类实现样式，CSS优先的配置
class-variance-authority - 用于管理组件样式变体
clsx + tailwind-merge - 通过
```
cn()
```
工具函数实现条件类组合

Project Structure

项目结构

Components installed to

@/modules/cores/shadcn/components/ui/

following SOLID architecture. Utils at

@/modules/cores/lib/utils.ts

with

cn()

helper function.

组件按照SOLID架构安装至

@/modules/cores/shadcn/components/ui/

。工具函数存放于

@/modules/cores/lib/utils.ts

，包含

cn()

辅助函数。

MCP Server Integration

MCP服务器集成

Create

.mcp.json

at project root for Claude Code integration with shadcn registry.

在项目根目录创建

.mcp.json

文件，用于Claude Code与shadcn注册表的集成。

Available MCP Tools

可用的MCP工具

```
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.

```
mcp__shadcn__search_items_in_registries
```
- 搜索可用组件
```
mcp__shadcn__view_items_in_registries
```
- 查看组件源代码

mcp__shadcn__get_item_examples_from_registries

- 获取使用示例

```
mcp__shadcn__get_add_command_for_items
```
- 获取安装命令

完整的MCP设置请查看installation.md。

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

分类	组件	主要参考文档
初始化设置	初始化、配置、主题、图标	installation.md
表单	按钮、输入框、Field、选择器、复选框、开关、滑块	field-patterns.md
覆盖层	对话框、侧边栏、抽屉、弹出框、提示框、悬停卡片	dialog.md
反馈	告警、提示通知（Sonner）、进度条、骨架屏、加载指示器	toast.md
数据展示	表格、徽章、头像、日历、图表、轮播	table.md
导航	面包屑、下拉菜单、命令面板、侧边栏、标签页	sidebar.md
布局	卡片、折叠面板、分隔线、滚动区域、可调整大小组件	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

Field组件 - 使用新的Field模式保证表单字段结构一致
默认使用服务端组件 - 仅在需要交互时添加
```
'use client'
```
指令
使用Sonner实现提示通知 - 采用现代提示通知组件替代旧版组件
优先使用MCP工具 - 在实现前使用
```
mcp__shadcn__*
```
工具进行探索
通过CSS变量实现主题定制 - 在
```
globals.css
```
的
```
:root
```
中自定义颜色
可访问性 - 依赖Radix UI的键盘导航和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

需求	参考文档
初始设置	installation.md, configuration.md
表单模式	field-patterns.md, form-examples.md
主题定制	theming.md
数据表格	table.md
模态对话框	dialog.md, alert-dialog.md
导航	sidebar.md, navigation-menu.md