Tailwind v4

它来了！Tailwind v4 和 React 19。准备好让你尝试了。你今天就可以开始使用它。

🌐 It’s here! Tailwind v4 and React 19. Ready for you to try out. You can start using it today.

有什么新东西

🌐 What's New

• 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 开始。

试用

🌐 Try It Out

你可以从今天开始使用 Tailwind v4 + React 19。请参阅下面的框架特定指南，了解如何入门。

🌐 You can start using Tailwind v4 + React 19 today. See the framework specific guides below for how to get started.

升级你的项目

🌐 Upgrade Your Project

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

🌐 One of the major advantages of using shadcn/ui is that the code you end up with is exactly what you'd write yourself. There are no hidden abstractions.

这意味着当依赖有新版本时，你只需遵循官方升级路径即可。

🌐 This means when a dependency has a new release, you can just follow the official upgrade paths.

以下是如何升级你现有的项目（完整文档正在制作中）：

🌐 Here's how to upgrade your existing projects (full docs are on the way):

1. 遵循 Tailwind v4 升级指南

🌐 1. Follow the Tailwind v4 Upgrade Guide

• 通过遵循官方升级指南升级到 Tailwind v4：https://tailwind.nodejs.cn/docs/upgrade-guide
• 使用 @tailwindcss/upgrade@next 代码修改工具移除已废弃的实用类并更新 Tailwind 配置。

2. 更新你的 CSS 变量

🌐 2. Update your CSS variables

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

🌐 The codemod will migrate your CSS variables as references under the @theme directive.

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。

🌐 This works. But to make it easier to work with colors and other variables, we'll need to move the hsl wrappers and use @theme inline.

以下是操作方法：

🌐 Here's how you do it:

1. 将 :root 和 .dark 移出 @layer 基地。
2. 将颜色值封装在 hsl() 中
3. 将 inline 选项添加到 @theme 中，即 @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 中的颜色值。

🌐 This change makes it much simpler to access your theme variables in both utility classes and outside of CSS for eg. using color values in JavaScript.

3. 更新图表的颜色

🌐 3. Update colors for charts

既然主题颜色随 hsl() 一起提供，你可以在你的 chartConfig 中移除封装器：

🌐 Now that the theme colors come with hsl(), you can remove the wrapper in your 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-* 工具

🌐 4. Use new size-* utility

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

🌐 The new size-* utility (added in Tailwind v3.4), is now fully supported by tailwind-merge. You can replace w-* h-* with the new size-* utility:

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

5. 更新你的依赖

🌐 5. Update your dependencies

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

6. 删除 forwardRef

🌐 6. Remove forwardRef

你可以使用 remove-forward-ref 代码修改工具将你的 forwardRef 迁移到 props，或者手动更新这些基础组件。

🌐 You can use the remove-forward-ref codemod to migrate your forwardRef to props or manually update the primitives.

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

🌐 For the codemod, see https://github.com/reactjs/react-codemod#remove-forward-ref.

如果你想手动执行此操作，请按照以下步骤操作：

🌐 If you want to do it manually, here's how to do it step by step:

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

之前

🌐 Before

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"

之后

🌐 After

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}
    />
  )
}

更新日志

🌐 Changelog

2025年3月19日 - 弃用 tailwindcss-animate

🌐 March 19, 2025 - Deprecate tailwindcss-animate

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

🌐 We've deprecated tailwindcss-animate in favor of tw-animate-css.

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

🌐 New project will have tw-animate-css installed by default.

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

🌐 For existing projects, follow the steps below to migrate.

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日 - 新暗色模式颜色

🌐 March 12, 2025 - New Dark Mode Colors

我们重新审视了夜间模式的颜色，并对其进行了更新，使其更易于使用。

🌐 We've revisited the dark mode colors and updated them to be more accessible.

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

🌐 If you're running an existing Tailwind v4 project (not an upgraded one¹), you can update your components to use the new dark mode colors by re-adding your components using the CLI².

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

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