shadcn/ui 是由 shadcn 开发的 Tailwind Css 组件框架，可将组件自动拷贝至项目中。

https://ui.shadcn.com

初始化

各个框架中的安装文档：

https://ui.shadcn.com/docs/installation

在 Next.js 项目中执行初始化：

npx shadcn@latest init

它会检查项目的 tailwind 安装情况，注意需要项目内的 css 文件去引用 @tailwind 的内容，否则会识别为未配置 tailwind 。

进行了这些改动：

• lib/utils.ts 新增了一个 cn 方法，引用了 clsx 和 tailwind-merge 包，用于合并 tailwind 类名
• tailwind.config.ts 配置了一些变量、颜色、动画
• global.css 配置了一些 css 变量，用于 tailwind 自定义颜色
• components.json 是 shadcn/ui 的配置文件，有几个配置初始化后不能再设置

主题色

• 文档: https://ui.shadcn.com/docs/theming
• 主题配置: https://ui.shadcn.com/themes

有两种设置主题色的模式：tailwind 工具类和 css 变量。

• tailwind 工具类模式是直接写 tailwind 调色板中的颜色类名，不方便调整为自己的主题色。如无主题色定制需求，可使用这种模式。这种对配置文件和公共样式的改动比较小。
• css 变量是更推荐的用法，在主题配置页面，拷贝代码时，也是使用 css 变量。
  • 通过的自定义颜色不算太多，每个颜色的用途在 文档 中都有详细描述。
  • 使用 css 变量的模式，相当于 shadcn ui 为我们搭建了一套设计体系，可以直接沿用它的设计体系，也可以在其基础上进行拓展。

CLI 使用

增加组件

npx shadcn@latest add button

安装组件时打开文档对照一下，有些组件会要求更新 tailwind.config.js 配置文件。

对比组件

对比现有组件与最新的效果：

npx shadcn diff

对于现有组件，它会提示是否覆盖。如果我们没有定制组件，就可以使用 add 直接覆盖，有定制组件，就 diff 查看区别，覆盖后再将定制的功能同步过来。

本地使用 cli 工具

如果在无法访问 https://ui.shadcn.com/ 的环境下，也可以本地运行 cli 工具。

把 https://github.com/shadcn-ui/ui/tree/main/apps/www/public/ 的内容下载到本地，然后通过本地服务器部署。

然后指定环境变量，运行命令：

REGISTRY_URL=http://localhost:3333/r npx shadcn@latest init

图标

shadcn-ui 内部使用了第三方图标库。

• 默认风格，使用 lucide-react ，文档： https://lucide.dev/icons/
• new-york 风格，使用 @radix-ui/react-icons ，文档： https://www.radix-ui.com/icons

项目需要使用到图标，可在对应的图标库中选择图标使用。

黑暗模式

https://ui.shadcn.com/docs/dark-mode

shadcn-ui 对黑暗模式支持较好。

• Next.js 安装 next-themes 简单配置即可。
• vite 这里文档帮助实现了一个控制黑暗模式的 provider

更多资源

可在社区中寻找缺失的组件：

• 时间选择器 https://time.openstatus.dev/
• 富文本编辑器 https://platejs.org/

shadcn-ui 的流行得产生了很多围绕它的生态了：

https://github.com/birobirobiro/awesome-shadcn-ui