Tailwind v4

它来了！Tailwind v4 和 React 19 已就绪，供你试用。你今天就可以开始使用它。

新增内容

• CLI 现在可以初始化使用 Tailwind v4 的项目。
• 完全支持新的 @theme 指令和 @theme inline 选项。
• 所有组件已更新以适配 Tailwind v4 和 React 19。
• 我们已移除 forwardRefs 并调整了类型。
• 每个基础组件现在都有一个 data-slot 属性以便样式设计。
• 我们修复并清理了组件的样式。
• 我们正在废弃 toast 组件，转而使用 sonner。
• 按钮现在使用默认光标。
• 我们正在废弃 default 样式。新项目将使用 new-york。
• HSL 颜色现已转换为 OKLCH。

注意：这是非破坏性更新。你现有的 Tailwind v3 和 React 18 应用仍将正常运行。当你添加新组件时，它们仍将使用 v3 和 React 18，直到你进行升级。只有新项目会默认使用 Tailwind v4 和 React 19。

实时查看

我在这里整理了一个包含所有更新组件的演示：https://v4.shadcn.com

请查看并测试这些组件。如果发现任何问题，请在 GitHub 上告诉我。

试用

你可以使用 CLI 的 canary 版本测试 Tailwind v4 + React 19。以下是针对特定框架的入门指南。

升级你的项目

使用 shadcn/ui 的一个主要优势是你最终得到的代码正是你自己会编写的代码，没有隐藏的抽象层。

这意味着当依赖项有新版本发布时，你只需按照官方的升级路径操作即可。

以下是如何升级现有项目的方法（完整文档即将推出）：

1. 遵循 Tailwind v4 升级指南

• 按照官方升级指南升级到 Tailwind v4：https://tailwindcss.com/docs/upgrade-guide
• 使用 @tailwindcss/upgrade@next codemod 删除已废弃的实用类并更新 Tailwind 配置。

2. 更新你的 CSS 变量

codemod 会将你的 CSS 变量迁移为 @theme 指令下的引用。

@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 0 0% 3.9%;
  }
}
 
@theme {
  --color-background: hsl(var(--background));
  --color-foreground: hsl(var(--foreground));
}

这样是可行的。但为了更方便地处理颜色和其他变量，我们需要移动 hsl 包装并使用 @theme inline。

以下是具体步骤：

1. 将 :root 和 .dark 从 @layer base 中移出。
2. 将颜色值包裹在 hsl() 中。
3. 为 @theme 添加 inline 选项，即 @theme inline。
4. 从 @theme 中移除 hsl() 包装。

:root {
  --background: hsl(0 0% 100%); // <-- 包裹在 hsl 中
  --foreground: hsl(0 0% 3.9%);
}
 
.dark {
  --background: hsl(0 0% 3.9%); // <-- 包裹在 hsl 中
  --foreground: hsl(0 0% 98%);
}
 
@theme inline {
  --color-background: var(--background); // <-- 移除 hsl
  --color-foreground: var(--foreground);
}
 

这一更改使得在实用类和 CSS 外部（例如在 JavaScript 中使用颜色值）访问主题变量变得更加简单。

3. 更新图表的颜色

现在主题颜色已包含 hsl()，你可以在 chartConfig 中移除包装：

const chartConfig = {
  desktop: {
    label: "Desktop",
-    color: "hsl(var(--chart-1))",
+    color: "var(--chart-1)",
  },
  mobile: {
    label: "Mobile",
-   color: "hsl(var(--chart-2))",
+   color: "var(--chart-2)",
  },
} satisfies ChartConfig

4. 使用新的 size-* 实用类

新的 size-* 实用类（在 Tailwind v3.4 中添加）现已得到 tailwind-merge 的完全支持。你可以将 w-* h-* 替换为新的 size-* 实用类：

- w-4 h-4
+ size-4

5. 更新你的依赖项

pnpm up "@radix-ui/*" cmdk lucide-react recharts tailwind-merge clsx --latest

6. 移除 forwardRef

你可以使用 remove-forward-ref codemod 将 forwardRef 迁移到 props，或者手动更新基础组件。

有关 codemod 的信息，请参见 https://github.com/reactjs/react-codemod#remove-forward-ref。

如果你想手动操作，以下是逐步说明：

1. 将 React.forwardRef<...> 替换为 React.ComponentProps<...>。
2. 从组件中移除 ref={ref}。
3. 添加一个 data-slot 属性。这将有助于使用 Tailwind 进行样式设计。
4. 你可以选择将其转换为命名函数并移除 displayName。

Before

const AccordionItem = React.forwardRef<
  React.ElementRef<typeof AccordionPrimitive.Item>,
  React.ComponentPropsWithoutRef<typeof AccordionPrimitive.Item>
>(({ className, ...props }, ref) => (
  <AccordionPrimitive.Item
    ref={ref}
    className={cn("border-b last:border-b-0", className)}
    {...props}
  />
))
AccordionItem.displayName = "AccordionItem"

After

function AccordionItem({
  className,
  ...props
}: React.ComponentProps<typeof AccordionPrimitive.Item>) {
  return (
    <AccordionPrimitive.Item
      data-slot="accordion-item"
      className={cn("border-b last:border-b-0", className)}
      {...props}
    />
  )
}

更新日志

2025年3月12日 - 新暗模式颜色

我们重新审视了暗模式颜色并更新了它们以提高可访问性。

如果你运行的是现有的 Tailwind v4 项目（而不是升级的项目¹），你可以通过使用 CLI 重新添加组件来更新你的组件以使用新的暗模式颜色²。