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。

试用

您今天可以使用 CLI 的 canary 版本测试 Tailwind v4 + React 19。请参阅下面的特定框架指南以了解如何开始。

升级您的项目

使用 shadcn/ui 的主要优势之一是您最终得到的代码与您自己编写的代码完全相同。没有隐藏的抽象。

这意味着当一个依赖项有新版本发布时，您只需遵循官方的升级路径即可。

以下是升级现有项目的方法（完整文档即将发布）

1. 遵循 Tailwind v4 升级指南

• 按照官方升级指南升级到 Tailwind v4：https://tailwind.org.cn/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: "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-* 工具类。

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，或手动更新原始元素。

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

如果您想手动操作，以下是分步说明：

1. 将 React.forwardRef<...> 替换为 React.ComponentProps<...>。
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. 将 @import "tw-animate-css" 添加到您的 globals.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
Copy