Tailwind v4

它来了！Tailwind v4 和 React 19。现在就可以开始试用。你今天就能用上它。

有什么新变化

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

注意：这是非破坏性更新。你现有的 Tailwind v3 和 React 18 应用仍然可以正常工作。即使你添加新组件，在升级之前它们也仍然会保持在 v3 和 React 18。只有新项目才会默认使用 Tailwind v4 和 React 19。

试试看

你今天就可以开始使用 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 指令下。

Copy@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() 包装。

Copy:root {
  --background: hsl(0 0% 100%); // <-- Wrap in hsl
  --foreground: hsl(0 0% 3.9%);
}
 
.dark {
  --background: hsl(0 0% 3.9%); // <-- Wrap in hsl
  --foreground: hsl(0 0% 98%);
}
 
@theme inline {
  --color-background: var(--background); // <-- Remove hsl
  --color-foreground: var(--foreground);
}

这样一来，无论是在工具类中还是在 CSS 之外访问主题变量都更简单，例如在 JavaScript 中使用颜色值。

3. 更新图表颜色

既然主题颜色现在已经带有 hsl()，你就可以在 chartConfig 中移除外层包装：

Copyconst chartConfig = {
  desktop: {
    label: "桌面端",
-    color: "hsl(var(--chart-1))",
+    color: "var(--chart-1)",
  },
  mobile: {
    label: "移动端",
-   color: "hsl(var(--chart-2))",
+   color: "var(--chart-2)",
  },
} satisfies ChartConfig

4. 使用新的 size-* 工具类

新的 size-* 工具类（Tailwind v3.4 中新增）现在已经被 tailwind-merge 完整支持。你可以用新的 size-* 工具类替换 w-* h-*：

Copy- w-4 h-4
+ size-4

5. 更新依赖

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

6. 移除 forwardRef

你可以使用 remove-forward-ref codemod 将你的 forwardRef 迁移为 props，或者手动更新这些 primitives。

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

如果你想手动处理，可以按以下步骤进行：

1. 用 React.ComponentProps<...> 替换 React.forwardRef<...>。
2. 从组件中移除 ref={ref}。
3. 添加 data-slot 属性。这在使用 Tailwind 进行样式化时会很有用。
4. 你也可以选择转换为具名函数并移除 displayName。

迁移前

Copyconst 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"

迁移后

Copyfunction 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 月 19 日 - 弃用 tailwindcss-animate

我们已弃用 tailwindcss-animate，改用 tw-animate-css。

新项目会默认安装 tw-animate-css。

对于现有项目，请按照以下步骤迁移。

1. 从依赖中移除 tailwindcss-animate。
2. 从你的 globals.css 文件中移除 @plugin 'tailwindcss-animate'。
3. 将 tw-animate-css 作为开发依赖安装。
4. 在你的 globals.css 文件中添加 @import "tw-animate-css"。

Copy- @plugin 'tailwindcss-animate';
+ @import "tw-animate-css";

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

我们重新审视了深色模式颜色，并将它们更新得更易访问。

如果你正在运行一个现有的 Tailwind v4 项目（不是升级得到的项目¹），你可以通过使用 CLI 重新添加组件²，让组件改用新的深色模式颜色。

Copygit add .
git commit -m "..."

pnpmnpmyarnbun
pnpm dlx shadcn@latest add --all --overwrite
复制