shadcn/ui 与 Base UI 集成指南：避免 Radix UI 错误，正确使用 render 属性

shadcn-baseui by thunderboltdev/shadcn-baseui

105 周安装量

GitHub

安装命令

npx skills add https://github.com/thunderboltdev/shadcn-baseui --skill shadcn-baseui

UI组件库开发 React

🇨🇳中文介绍

shadcn/ui + Base UI 指南

一份在使用 Base UI 时配合 shadcn/ui 组件的指南。防止 LLMs 错误地建议 Radix UI 模式（如 asChild 等）。

⚠️ 重要提示： 在建议任何代码之前，请通过检查 components.json 来验证这是否是一个 Base UI 项目。style 字段应以 "base-" 开头（例如 "base-vega"、"base-nova"、"base-maia"、"base-lyra"、"base-mira"）。如果它以其他内容开头，则本技能不适用。

确保已安装 @base-ui/react 包。如果未安装，请使用相应的包管理器进行安装。

插槽模式

🇺🇸English

shadcn/ui + Base UI Guidelines

A guide for using shadcn/ui components when working with Base UI. Prevents LLMs from incorrectly suggesting Radix UI patterns (asChild, etc.).

⚠️ CRITICAL: Before suggesting any code, verify this is a Base UI project by checking components.json. The style field should start with "base-" (e.g., "base-vega", "base-nova", "base-maia", "base-lyra", "base-mira"). If it starts with something else, this skill does not apply.

Ensure the @base-ui/react package is installed. If not, install it using the appropriate package manager.

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

867,400 周安装

Vercel React 最佳实践指南 | 58条Next.js性能优化规则与代码重构

283,600 周安装

Vercel Web界面规范检查工具 - 自动检测代码是否符合Web设计指南

228,700 周安装

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

157,400 周安装

Radix UI 和 Base UI 之间的主要区别在于插槽模式。Radix UI 使用 asChild，而 Base UI 使用 render 属性。请始终使用 render 属性而非 asChild。

规则： 对于所有触发器/包装器组件，始终使用 render 属性代替 asChild。

适用于：DialogTrigger、AlertDialogTrigger、PopoverTrigger、DropdownMenuTrigger、TooltipTrigger、SelectTrigger、TabsTrigger、AccordionTrigger、Button（当包装链接时）等。

// ❌ 错误
<DialogTrigger asChild>
  <Button variant="outline">Click me</Button>
</DialogTrigger>

// ✅ 正确
<DialogTrigger render={<Button variant="outline" />}>
  Click me
</DialogTrigger>

// ✅ 同样正确
<DialogTrigger render={<Button variant="outline">Click me</Button>} />

除了插槽模式之外，只有以下组件具有不同的属性。在使用这些组件时，请遵循组件特定的指南。

Accordion 组件没有 type 属性，请使用布尔类型的 multiple 属性代替。defaultValue 属性始终基于数组。

<Accordion type="single" defaultValue="item-1">
  <AccordionItem value="item-1">
    // ...
  </AccordionItem>
</Accordion>

// ✅ 正确
<Accordion defaultValue={["item-1"]}>
  <AccordionItem value="item-1">
    // ...
  </AccordionItem>
</Accordion>

// ❌ 错误
<Accordion type="multiple" defaultValue={["item-1", "item-2"]}>
  <AccordionItem value="item-1">...</AccordionItem>
  <AccordionItem value="item-2">...</AccordionItem>
</Accordion>

// ✅ 正确
<Accordion multiple defaultValue={["item-1", "item-2"]}>
  <AccordionItem value="item-1">...</AccordionItem>
  <AccordionItem value="item-2">...</AccordionItem>
</Accordion>

Button（特殊情况）

当将 Button 渲染为非按钮元素（如 Link）时，必须添加 nativeButton={false}。

// ❌ 错误 - Radix 模式
import Link from "next/link";

<Button asChild variant="ghost">
  <Link href="/dashboard">Dashboard</Link>
</Button>

// ✅ 正确 - Base UI 模式
import Link from "next/link";

<Button render={<Link href="/dashboard" />} variant="ghost" nativeButton={false}>
  Dashboard
</Button>

position 属性被一个布尔属性 alignItemWithTrigger 取代，该属性默认为 true。

// ❌ 错误
<SelectContent position="popper">
  // ...
</SelectContent>

// ✅ 正确
<SelectContent alignItemWithTrigger={false}>
  // ...
</SelectContent>

The major difference between Radix UI and Base UI is the slot pattern. Radix UI uses asChild, while Base UI uses the render prop. Always use render prop over asChild.

Rule: Always use render prop instead of asChild for ALL trigger/wrapper components.

Applies to: DialogTrigger, AlertDialogTrigger, PopoverTrigger, DropdownMenuTrigger, TooltipTrigger, SelectTrigger, TabsTrigger, AccordionTrigger, Button (when wrapping links), etc.

// ❌ INCORRECT
<DialogTrigger asChild>
  <Button variant="outline">Click me</Button>
</DialogTrigger>

// ✅ CORRECT
<DialogTrigger render={<Button variant="outline" />}>
  Click me
</DialogTrigger>

// ✅ ALSO CORRECT
<DialogTrigger render={<Button variant="outline">Click me</Button>} />

Beyond the slot pattern, only the following components have different props. When using these components following the component specific guide.

There's no type prop on the Accordion component, use the boolean multiple prop instead. The defaultValue prop is always array based.

<Accordion type="single" defaultValue="item-1">
  <AccordionItem value="item-1">
    // ...
  </AccordionItem>
</Accordion>

// ✅ CORRECT
<Accordion defaultValue={["item-1"]}>
  <AccordionItem value="item-1">
    // ...
  </AccordionItem>
</Accordion>

// ❌ INCORRECT
<Accordion type="multiple" defaultValue={["item-1", "item-2"]}>
  <AccordionItem value="item-1">...</AccordionItem>
  <AccordionItem value="item-2">...</AccordionItem>
</Accordion>

// ✅ CORRECT
<Accordion multiple defaultValue={["item-1", "item-2"]}>
  <AccordionItem value="item-1">...</AccordionItem>
  <AccordionItem value="item-2">...</AccordionItem>
</Accordion>

Button (Special Case)

When rendering a Button as a non-button element (like a Link), you must add nativeButton={false}.

// ❌ INCORRECT - Radix pattern
import Link from "next/link";

<Button asChild variant="ghost">
  <Link href="/dashboard">Dashboard</Link>
</Button>

// ✅ CORRECT - Base UI pattern
import Link from "next/link";

<Button render={<Link href="/dashboard" />} variant="ghost" nativeButton={false}>
  Dashboard
</Button>

The position prop is replaced with a boolean prop alignItemWithTrigger which defaults to true.

// ❌ INCORRECT
<SelectContent position="popper">
  // ...
</SelectContent>

// ✅ CORRECT
<SelectContent alignItemWithTrigger={false}>
  // ...
</SelectContent>

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

116,600 周安装

shadcn/ui 与 Base UI 集成指南：避免 Radix UI 错误，正确使用 render 属性

🇨🇳中文介绍

shadcn/ui + Base UI 指南

插槽模式

🇺🇸English

shadcn/ui + Base UI Guidelines

相关 Skills

属性

Accordion

Button（特殊情况）

Select

Slot Pattern

Props

Accordion

Button (Special Case)

Select

最新 Skills