简介

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

什么是 shadcn/ui？

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

“不是组件库”是什么意思？

这意味着你不需要将其作为依赖项安装。它不通过 npm 或 yarn 分发。

你只需要挑选你需要的组件。将代码复制并粘贴到你的项目中，并根据你的需要进行定制。代码是属于你的。

为什么要这样做？

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

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

安装

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

项目初始化

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

npx shadcn@latest init

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

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

支持的框架

不论你使用的是哪种现代 React 框架，我们都提供了适配方案：

Next.js：大多数应用的首选推荐。
Vite：适用于不含 SSR 的 React 项目。
Astro：内容驱动型网站的绝佳选择。
Remix：全栈 React 应用。

CLI 命令行工具

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

常用命令

init

初始化项目并创建 `components.json` 配置文件。

npx shadcn@latest init

add

向项目中添加特定组件。例如添加按钮组件：

npx shadcn@latest add button

常用选项

-y, --yes：跳过确认提示，直接执行。
-o, --overwrite：覆盖已存在的组件文件。
-c, --cwd <path>：指定工作目录。

主题定制

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

CSS 变量配置

我们在全局 CSS 文件中使用 `:root` 定义颜色变量。所有的变量都采用 HSL 格式以便于 Tailwind 进行透明度处理。

                        :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%;
                        /* ...其他变量 */
                        }
                    

定制约定

HSL 格式：所有颜色必须遵循 HSL 定义（如 0 0% 100%）。
无障碍性：在定制主色调时，请务必检查背景与前景的对比度。
圆角半径：通过 --radius 变量统一控制全站组件圆角。

暗黑模式

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

Next.js 实现步骤

安装依赖：npm install next-themes
在根布局中使用 ThemeProvider 包裹子组件。
添加一个模式切换按钮 (Mode Toggle)。

                        import { ThemeProvider } from "next-themes"

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

排版规范

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

常用基础样式

一级标题 (H1)

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

二级标题 (H2)

scroll-m-20 border-b pb-2 text-3xl font-semibold
                                tracking-tight

正文段落 (P)

leading-7 [&:not(:first-child)]:mt-6

调用示例

                        export function TypographyH1() {
                        return (
                        <h1 className="scroll-m-20 text-4xl font-extrabold tracking-tight lg:text-5xl">
                        这是一个极致极简的文档标题
                        </h1>
                        )
                        }
                    

Accordion 手风琴

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

说明

此组件基于 Radix UI 的 Accordion 原语构建，并由 Tailwind CSS 定义样式。它完全支持键盘导航和屏幕阅读器。

安装

npx shadcn@latest add accordion

用法示例

                        import {
                        Accordion,
                        AccordionContent,
                        AccordionItem,
                        AccordionTrigger,
                        } from "@/components/ui/accordion"

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

API 参考

Accordion 根容器。类型可选 single 或 multiple。
AccordionItem 包含触点和内容的包装器。
AccordionTrigger 触发展开/关闭的标题部分。
AccordionContent 被折叠的面板内容。

Button 按钮

具有多种样式变体和尺寸的通用按钮。支持加载状态、图标集成以及作为子元素分发。

安装

npx shadcn@latest add button

用法

                        import { Button } from "@/components/ui/button"

                        export function ButtonDemo() {
                        return <Button variant="outline">确定</Button>
                        }
                    

属性 (Props)

属性	类型	默认值	说明
variant	default \| outline \| ghost...	default	视觉变体
size	default \| sm \| lg \| icon	default	尺寸步阶
asChild	boolean	false	是否渲染为子元素容器

Dialog 对话框

覆盖在主窗口之上的模态弹出框。通常用于关键性确认或输入任务。

说明

对话框会在打开时锁定背景滚动，并提供完整的焦点捕获（Focus Trap）与无障碍属性（Aria-labelledby / describedby）。

安装

npx shadcn@latest add dialog

用法示例

                        import {
                        Dialog,
                        DialogContent,
                        DialogDescription,
                        DialogHeader,
                        DialogTitle,
                        DialogTrigger,
                        } from "@/components/ui/dialog"

                        export function DialogDemo() {
                        return (
                        <Dialog>
                        <DialogTrigger>打开对话框</DialogTrigger>
                        <DialogContent>
                        <DialogHeader>
                        <DialogTitle>确认此操作？</DialogTitle>
                        <DialogDescription>
                        此操作无法撤销。系统将永久删除相关的用户记录。
                        </DialogDescription>
                        </DialogHeader>
                        </DialogContent>
                        </Dialog>
                        )
                        }
                    

核心组件

Dialog 主容器，通过 Context 共享状态。
DialogTrigger 交互触发器，通常为一个按钮。
DialogContent 实际渲染在 Portal 中的弹出内容。
DialogHeader / Footer 预置的结构化布局。