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://tailwind.org.cn/docs/upgrade-guide
• 使用 @tailwindcss/upgrade@next codemod 删除已弃用的 utility 类并更新 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%); // <-- 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);
}

此更改使在 utility 类和 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-* utility

新的 size-* utility（在 Tailwind v3.4 中添加）现在完全受 tailwind-merge 支持。你可以用新的 size-* utility 替换 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 或手动更新 primitives。

对于 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. 将 @import "tw-animate-css" 添加到你的 globals.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