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://tailwindcss.zhcndoc.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));
}

上述写法可用，但为了便于在实用类和 CSS 外使用颜色等变量，我们需要把 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%); /* <-- 用 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 外（如 JS 中）访问主题变量更加简单。

3. 更新图表颜色

由于主题色现在已被 hsl() 包裹，图表配置中的颜色可以去掉 hsl 包裹：

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-* 工具类

Tailwind v3.4 新引入的 size-* 工具类现已被 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 或手动更新原始组件。

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
Copy