Tailwind v4

Tailwind v4 与 React 19 已经发布——马上就能体验！

新特性

• CLI 可直接初始化 Tailwind v4 项目。
• 完整支持全新的 @theme 指令与 @theme inline。
• 所有组件已更新以兼容 Tailwind v4 与 React 19。
• 移除 forwardRef，并调整了类型定义。
• 每个原子组件都新增了 data-slot 属性，方便样式定制。
• 修复并统一了组件样式。
• 弃用 toast 组件，推荐改用 sonner。
• Button 现在使用默认光标。
• 弃用 default 风格，新项目默认使用 new-york。
• HSL 颜色统一转换为 OKLCH。

注意：这不是破坏性更新。 已经使用 Tailwind v3 + React 18 的项目仍可正常运行；在升级前安装新组件仍会保持 v3/React 18 版本。只有全新项目会默认启用 Tailwind v4 与 React 19。

立即体验

使用 CLI 的 canary 发布即可体验 Tailwind v4 + React 19。各框架的启动指南请参阅下方链接。

Upgrade Your Project

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. Follow the Tailwind v4 Upgrade Guide

• Upgrade to Tailwind v4 by following the official upgrade guide: https://tailwindcss.com/docs/upgrade-guide
• Use the @tailwindcss/upgrade@next codemod to remove deprecated utility classes and update tailwind config.

2. Update your CSS variables

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

复制@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 0 0% 3.9%;
  }
}
 
@theme {
  --color-background: hsl(var(--background));
  --color-foreground: hsl(var(--foreground));
}

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. Move :root and .dark out of the @layer base.
2. Wrap the color values in hsl()
3. Add the inline option to @theme i.e @theme inline
4. Remove the hsl() wrappers from @theme

复制: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);
}

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. Update colors for charts

Now that the theme colors come with hsl(), you can remove the wrapper in your 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. Use new size-* utility

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:

复制- w-4 h-4
+ size-4

5. Update your dependencies

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

6. Remove forwardRef

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

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. Replace React.forwardRef<...> with React.ComponentProps<...>
2. Remove ref={ref} from the component.
3. Add a data-slot attribute. This will come in handy for styling with Tailwind.
4. You can optionally convert to a named function and remove the displayName.

Before

复制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"

After

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

Changelog

March 19, 2025 - Deprecate tailwindcss-animate

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

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

For existing projects, follow the steps below to migrate.

1. Remove tailwindcss-animate from your dependencies.
2. Remove the @plugin 'tailwindcss-animate' from your globals.css file.
3. Install tw-animate-css as a dev dependency.
4. Add the @import "tw-animate-css" to your globals.css file.

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

March 12, 2025 - New Dark Mode Colors

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

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².

复制git add .
git commit -m "..."

pnpmnpmyarnbun
pnpm dlx shadcn@latest add --all --overwrite
复制