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. 将 inline 选项添加到 @theme，即 @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()，您可以在图表配置中移除包装：

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。您可以用新的 size-* 工具类替换 w-* h-*：

- 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。

之前

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"

之后

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 月 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"。

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

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

我们对暗模式颜色进行了重新审视，并将其更新为更具可访问性。

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

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

pnpm dlx shadcn@latest add --all --overwrite