> For AI agents: the complete documentation index is available at https://rspress.rs/zh/llms.txt, the full documentation bundle is available at https://rspress.rs/zh/llms-full.txt.

# shadcn/ui

[shadcn/ui](https://ui.shadcn.com/) 是一组基于 Radix UI / Base UI 和 Tailwind CSS 构建的可复用组件集合。本指南介绍如何在 Rspress 文档站点中使用 shadcn/ui 组件。

在开始之前，请确保已经在项目中配置好 [Tailwind CSS](https://rspress.rs/zh/ui/tailwindcss.md)。


### 配置路径别名
在 `tsconfig.json` 的 `compilerOptions` 中添加 `paths`，以便正确解析 shadcn/ui 组件：
```json title="tsconfig.json"
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["doc", "src", "rspress.config.ts"]
}
```
### 创建 components.json 和工具函数
由于 `shadcn init` 无法自动识别 Rspress 框架，需要参考 [手动安装](https://ui.shadcn.com/docs/installation/manual) 来创建配置文件。
在项目根目录创建 `components.json` 文件，配置 shadcn/ui CLI：
```json title="components.json"
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "tailwind": {
    "config": "",
    "css": "tailwind.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "rsc": false,
  "tsx": true,
  "aliases": {
    "utils": "@/lib/utils",
    "components": "@/components",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  }
}
```
:::tip
- 省略了 `tailwind.config`，因为 Tailwind CSS v4 不再需要配置文件。
- `rsc` 设置为 `false`，因为 Rspress 不使用 React Server Components。
:::
然后安装依赖并创建工具函数：

```sh [npm]
npm install clsx tailwind-merge class-variance-authority
```

```sh [yarn]
yarn add clsx tailwind-merge class-variance-authority
```

```sh [pnpm]
pnpm add clsx tailwind-merge class-variance-authority
```

```sh [bun]
bun add clsx tailwind-merge class-variance-authority
```

```sh [deno]
deno add npm:clsx npm:tailwind-merge npm:class-variance-authority
```
```ts title="src/lib/utils.ts"
import { type ClassValue, clsx } from 'clsx';
import { twMerge } from 'tailwind-merge';

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}
```
### 添加组件
使用 `shadcn` CLI 添加所需组件，例如 Button：

```sh [npx]
npx shadcn@latest add button
```

```sh [yarn]
yarn dlx shadcn@latest add button
```

```sh [pnpm]
pnpm dlx shadcn@latest add button
```

```sh [bunx]
bunx shadcn@latest add button
```

```sh [deno]
deno run -A npm:shadcn@latest add button
```
### 在 MDX 中使用
在 MDX 文件中导入并使用组件：
```mdx title="doc/index.mdx"
import { Button } from '@/components/ui/button';

# 我的页面

<Button>点击我</Button>
<Button variant="outline">边框按钮</Button>
```

:::tip
shadcn/ui 不是传统的 npm 包，而是一组可复制粘贴的组件集合，你可以完全掌控组件代码并按需自定义。
:::