Back to Details

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:
  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.
在进行任何实现之前，使用
TeamCreate
生成3个Agent：
  1. fuse-ai-pilot:explore-codebase - 分析现有组件和模式
  2. fuse-ai-pilot:research-expert - 通过Context7/Exa验证最新的shadcn/ui文档
  3. 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的原因

FeatureBenefit
Copy/paste modelComponents copied to your project, full ownership
Radix UI foundationAccessibility built-in, unstyled primitives
Tailwind CSS stylingUtility-first, easy customization
TanStack Form readyModern form library with Field pattern
Server ComponentsRSC-compatible, optimal bundle size
Lucide iconsConsistent, customizable icon set
特性优势
复制粘贴模式组件可复制到你的项目中，完全拥有所有权
Radix UI基础内置可访问性，无样式基础组件
Tailwind CSS样式实用优先，易于自定义
兼容TanStack Form支持Field模式的现代表单库
服务端组件兼容兼容RSC，优化包体积
Lucide图标风格统一、可自定义的图标集

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

组件分类

CategoryComponentsPrimary Reference
SetupInit, configuration, theming, iconsinstallation.md
FormsButton, Input, Field, Select, Checkbox, Switch, Sliderfield-patterns.md
OverlayDialog, Sheet, Drawer, Popover, Tooltip, HoverCarddialog.md
FeedbackAlert, Toast (Sonner), Progress, Skeleton, Spinnertoast.md
Data DisplayTable, Badge, Avatar, Calendar, Chart, Carouseltable.md
NavigationBreadcrumb, DropdownMenu, Command, Sidebar, Tabssidebar.md
LayoutCard, Accordion, Separator, ScrollArea, Resizablecard.md
分类组件主要参考文档
初始化设置初始化、配置、主题、图标installation.md
表单按钮、输入框、Field、选择器、复选框、开关、滑块field-patterns.md
覆盖层对话框、侧边栏、抽屉、弹出框、提示框、悬停卡片dialog.md
反馈告警、提示通知（Sonner）、进度条、骨架屏、加载指示器toast.md
数据展示表格、徽章、头像、日历、图表、轮播table.md
导航面包屑、下拉菜单、命令面板、侧边栏、标签页sidebar.md
布局卡片、折叠面板、分隔线、滚动区域、可调整大小组件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
  1. Field组件 - 使用新的Field模式保证表单字段结构一致
  2. 默认使用服务端组件 - 仅在需要交互时添加
    'use client'
    指令
  3. 使用Sonner实现提示通知 - 采用现代提示通知组件替代旧版组件
  4. 优先使用MCP工具 - 在实现前使用
    mcp__shadcn__*
    工具进行探索
  5. 通过CSS变量实现主题定制 - 在
    globals.css
    的
    :root
    中自定义颜色
  6. 可访问性 - 依赖Radix UI的键盘导航和ARIA属性

Reference Guide

参考指南

NeedReference
Initial setupinstallation.md, configuration.md
Form patternsfield-patterns.md, form-examples.md
Theme customizationtheming.md
Data tablestable.md
Modal dialogsdialog.md, alert-dialog.md
Navigationsidebar.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