shadcn/ui docs/zh-cn
GitHub Twitter

简介

设计精美的组件，你可以直接复制并粘贴到你的应用程序中。无障碍支持。可高度定制。完全开源。

什么是 shadcn/ui？

这不是一个组件库。它是一套可重用的组件集合，你可以通过复制粘贴将其集成到你的项目中。

"不是组件库"是什么意思？

这意味着你不需要将其作为依赖项安装。它不通过 npm 或 yarn 分发。你只需要挑选你需要的组件，将代码复制并粘贴到你的项目中，并根据你的需要进行定制。代码是属于你的。

为什么要这样做？

我们相信开发者应该拥有对代码的绝对所有权和控制权。这让你能够决定组件是如何构建和装饰的，而不是受制于第三方库的 API 限制。

  • 基于 Radix UI 构建交互原语。
  • 使用 Tailwind CSS 处理样式。
  • 透明度：每一行代码都在你眼前，没有黑盒。
  • AI 友好：由于代码就在你的项目中，LLM 可以轻松阅读、理解并根据需求进行改进。

功能特性

  • 复制粘贴：组件直接添加到你的项目中，你可以随意修改。
  • 可访问性：基于 Radix UI 构建，支持键盘导航和屏幕阅读器。
  • 类型安全：完全用 TypeScript 编写，提供完整的类型定义。
  • 主题定制：使用 CSS 变量轻松定制主题。
  • 暗黑模式：内置暗黑模式支持。

组件概览

这里是所有可用组件的完整列表。我们正在持续添加更多组件。

可用组件

Accordion

手风琴折叠组件

Alert

警告提示组件

Alert Dialog

警告对话框

Avatar

头像组件

Badge

徽章标签

Button

按钮组件

Calendar

日历组件

Card

卡片容器

Carousel

轮播图组件

Chart

图表组件

Checkbox

复选框

Dialog

对话框

Input

输入框

Select

选择器

Table

表格组件

Tabs

标签页

Toast

消息提示

Tooltip

工具提示

找不到需要的组件？

可以尝试访问 Registry Directory 查找社区维护的组件。

安装

shadcn/ui 支持多种框架和工具。推荐的方式是使用 CLI 工具来初始化你的项目。

项目初始化

在你的终端中运行以下命令：

npx shadcn@latest init

该命令会引导你完成 `components.json` 的配置：

  • 是否使用 TypeScript？ (yes/no)
  • 你希望使用哪种样式风格？ (Default / New York)
  • 基础色系选择 (Slate / Gray / Zinc / Neutral / Stone)
  • 全局 CSS 文件的位置？
  • 是否使用 CSS 变量来处理颜色？

支持的框架

  • Next.js：大多数应用的首选推荐。
  • Vite：适用于不含 SSR 的 React 项目。
  • Astro：内容驱动型网站的绝佳选择。
  • Remix：全栈 React 应用。
  • Gatsby：静态站点生成器。
  • Laravel：PHP 全栈框架集成。

目录结构

了解 shadcn/ui 推荐的项目目录结构，帮助你组织组件和配置文件。

推荐结构

. ├── app/ │ ├── layout.tsx │ └── page.tsx ├── components/ │ └── ui/ │ ├── button.tsx │ └── ... ├── lib/ │ └── utils.ts ├── styles/ │ └── globals.css └── components.json

关键文件说明

  • components/ui/：存放所有 UI 组件的目录。
  • lib/utils.ts：包含 `cn` 工具函数用于合并 Tailwind 类名。
  • styles/globals.css：全局样式文件，包含 CSS 变量定义。
  • components.json：CLI 配置文件，定义组件安装路径。

RTL 支持

shadcn/ui 完全支持从右到左（RTL）的文本布局，适用于阿拉伯语、希伯来语等语言。

启用 RTL

在项目根目录添加 `dir="rtl"` 属性：

<html dir="rtl" lang="ar">...</html>

组件适配

  • 使用 Tailwind 的逻辑属性（如 `ms-` 代替 `ml-`）
  • 图标和箭头会自动翻转方向
  • 间距和对齐会自动调整

MCP Server

Model Context Protocol (MCP) 服务器让 AI 助手能够访问 shadcn/ui 的组件文档和代码。

什么是 MCP？

MCP 是一种协议，允许 AI 模型与外部工具和数据源进行交互。通过 shadcn/ui 的 MCP 服务器，AI 助手可以获取组件文档、查找特定组件的安装命令、获取组件的完整源代码。

配置使用

{ "mcpServers": { "shadcn": { "command": "npx", "args": ["-y", "@shadcn/mcp-server"] } } }

Registry

Registry 是 shadcn/ui 的组件分发系统，允许你从各种来源安装组件。

什么是 Registry？

Registry 是一个 JSON 文件，描述了组件的位置、依赖和文件结构。它让 CLI 能够知道如何正确安装组件。

从 URL 安装

npx shadcn@latest add https://example.com/registry/my-component.json

表单

shadcn/ui 提供了与主流表单库的集成方案，帮助你构建复杂的表单应用。

React Hook Form

推荐使用 React Hook Form 处理表单状态和验证：

npm install react-hook-form @hookform/resolvers zod

TanStack Form

如果你更喜欢 TanStack Form，我们也提供了相应的集成方案，具有完全类型安全的表单处理和异步验证支持。

更新日志

查看 shadcn/ui 的最新更新和改进。

v2.1.0

  • 新增 Button Group 组件
  • 新增 Input OTP 组件
  • 改进 Sidebar 组件的响应式行为
  • 修复 Dialog 组件的焦点捕获问题

v2.0.0

  • 全新的 CLI 工具
  • 支持 New York 样式风格
  • 改进的 Theming 系统
  • 新增 Chart 组件

CLI 命令行工具

使用 CLI 轻松添加组件并管理你的项目配置。

常用命令

init

npx shadcn@latest init

add

npx shadcn@latest add button

diff

npx shadcn@latest diff

常用选项

  • -y, --yes：跳过确认提示
  • -o, --overwrite：覆盖已存在的组件文件
  • -c, --cwd：指定工作目录
  • --all：添加所有可用组件

Monorepo 支持

在 Monorepo 项目中使用 shadcn/ui 的配置指南。

Turborepo 配置

packages/ └── ui/ ├── components/ui/ ├── lib/utils.ts └── package.json

注意事项

  • 确保 Tailwind CSS 配置在所有应用中共享
  • 在应用的 `tailwind.config.ts` 中添加共享包路径
  • 使用 workspace 协议安装本地包

JavaScript 支持

虽然 shadcn/ui 默认使用 TypeScript，但也支持纯 JavaScript 项目。

初始化 JavaScript 项目

npx shadcn@latest init # 在提示中选择：Would you like to use TypeScript? no

注意事项

  • 无法获得类型提示和自动补全
  • IDE 支持可能不如 TypeScript 完善
  • 建议新项目使用 TypeScript

主题定制

shadcn/ui 使用 CSS 变量 (CSS Variables) 进行主题化管理。这让你可以直接改变全局外观而无需修改单个组件逻辑。

CSS 变量配置

:root { --background: 0 0% 100%; --foreground: 222.2 47.4% 11.2%; --primary: 222.2 47.4% 11.2%; --border: 214.3 31.8% 91.4%; --radius: 0.5rem; }

基础色系

  • Zinc：中性灰色系（推荐）
  • Slate：带蓝调的灰色
  • Gray：纯灰色
  • Neutral：不带色调的灰色
  • Stone：带暖调的灰色

暗黑模式

通过 `next-themes` 或原生的 Tailwind `class` 策略为你的站点添加暗黑模式支持。

Next.js 实现步骤

import { ThemeProvider } from "next-themes" export function Providers({ children }) { return ( <ThemeProvider attribute="class" defaultTheme="system" enableSystem> {children} </ThemeProvider> ) }

排版规范

我们为标题、段落、列表等元素预设了一系列一致的排版样式。

常用基础样式

scroll-m-20 text-4xl font-extrabold tracking-tight lg:text-5xl

Accordion

一组垂直堆叠的交互式标题，每个标题都能展示一个内容区域。

安装

npx shadcn@latest add accordion

用法示例

import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from "@/components/ui/accordion" export function AccordionDemo() { return ( <Accordion type="single" collapsible> <AccordionItem value="item-1"> <AccordionTrigger>是否支持无障碍？</AccordionTrigger> <AccordionContent>是的。它完全遵循 WAI-ARIA 设计模式。</AccordionContent> </AccordionItem> </Accordion> ) }

Alert

用于向用户展示简短重要信息的组件，支持多种视觉变体。

安装

npx shadcn@latest add alert

用法示例

import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert" export function AlertDemo() { return ( <Alert> <AlertTitle>提示</AlertTitle> <AlertDescription>这是一条重要的提示信息。</AlertDescription> </Alert> ) }

Alert Dialog

用于需要用户确认的关键操作对话框，如删除操作。

安装

npx shadcn@latest add alert-dialog

Avatar

用户头像组件，支持图片、回退文字和图标。

安装

npx shadcn@latest add avatar

Badge

用于显示标签、状态或分类的小型徽章组件。

安装

npx shadcn@latest add badge

Breadcrumb

面包屑导航组件，显示当前页面在站点层级中的位置。

安装

npx shadcn@latest add breadcrumb

Button

具有多种样式变体和尺寸的通用按钮。

安装

npx shadcn@latest add button

变体

属性类型默认值
variantdefault | outline | ghost | link | destructive | secondarydefault
sizedefault | sm | lg | icondefault
asChildbooleanfalse

Calendar

日历组件，用于日期选择和展示。

安装

npx shadcn@latest add calendar

Card

卡片容器组件，用于组织和展示内容块。

安装

npx shadcn@latest add card

Carousel

轮播图组件，用于横向滚动展示内容。

安装

npx shadcn@latest add carousel

Chart

图表组件，基于 Recharts 构建，提供多种图表类型。

安装

npx shadcn@latest add chart

支持的图表类型

  • Area Chart：面积图
  • Bar Chart：柱状图
  • Line Chart：折线图
  • Pie Chart：饼图

Checkbox

复选框组件，用于多选场景。

安装

npx shadcn@latest add checkbox

Combobox

组合框组件，结合输入框和下拉列表，支持搜索和筛选。

安装

npx shadcn@latest add popover command

Command

命令面板组件，用于快速搜索和执行命令。

安装

npx shadcn@latest add command

Data Table

高级数据表格组件，基于 TanStack Table 构建。

安装

npx shadcn@latest add table

Date Picker

日期选择器组件。

安装

npx shadcn@latest add calendar popover

Dialog

覆盖在主窗口之上的模态弹出框。

安装

npx shadcn@latest add dialog

用法示例

import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogTrigger } from "@/components/ui/dialog" export function DialogDemo() { return ( <Dialog> <DialogTrigger>打开对话框</DialogTrigger> <DialogContent> <DialogHeader> <DialogTitle>确认此操作？</DialogTitle> </DialogHeader> </DialogContent> </Dialog> ) }

Drawer

抽屉组件，从屏幕边缘滑入的面板。

安装

npx shadcn@latest add drawer

Dropdown Menu

下拉菜单组件，用于显示操作选项列表。

安装

npx shadcn@latest add dropdown-menu

Hover Card

悬停卡片组件，鼠标悬停时显示额外信息。

安装

npx shadcn@latest add hover-card

Input

文本输入框组件。

安装

npx shadcn@latest add input

Label

表单标签组件。

安装

npx shadcn@latest add label

Menubar

菜单栏组件，通常用于应用程序顶部。

安装

npx shadcn@latest add menubar

Pagination

分页组件，用于导航多页内容。

安装

npx shadcn@latest add pagination

Popover

弹出层组件，在点击或悬停时显示内容。

安装

npx shadcn@latest add popover

Progress

进度条组件，显示任务完成进度。

安装

npx shadcn@latest add progress

Radio Group

单选按钮组组件。

安装

npx shadcn@latest add radio-group

Scroll Area

自定义滚动区域组件。

安装

npx shadcn@latest add scroll-area

Select

下拉选择器组件。

安装

npx shadcn@latest add select

Separator

分隔线组件，用于视觉上分隔内容。

安装

npx shadcn@latest add separator

Sheet

侧边面板组件，从屏幕边缘滑入。

安装

npx shadcn@latest add sheet

Sidebar

侧边栏组件，用于导航和内容组织。

安装

npx shadcn@latest add sidebar

Skeleton

骨架屏组件，用于内容加载占位。

安装

npx shadcn@latest add skeleton

Slider

滑块组件，用于选择数值范围。

安装

npx shadcn@latest add slider

Sonner

通知组件，基于 Sonner 库构建。

安装

npx shadcn@latest add sonner

Switch

开关组件，用于切换状态。

安装

npx shadcn@latest add switch

Table

表格组件，用于展示数据。

安装

npx shadcn@latest add table

Tabs

标签页组件，用于切换不同内容面板。

安装

npx shadcn@latest add tabs

Textarea

多行文本输入框组件。

安装

npx shadcn@latest add textarea

Toast

消息提示组件，用于显示临时通知。

安装

npx shadcn@latest add toast

Toggle

切换按钮组件，用于开关状态。

安装

npx shadcn@latest add toggle

Tooltip

工具提示组件，鼠标悬停时显示额外信息。

安装

npx shadcn@latest add tooltip