Tailwind CSS v4 Stable Release - Complete Migration Guide

January 9, 2026

English

Tailwind CSS v4 has officially hit stable! After months of alpha and beta testing, the new Rust-powered engine is ready for production.

Performance Improvements

The numbers are impressive:

Metric	v3	v4	Improvement
Full Build	500ms	50ms	10x faster
Incremental	150ms	1.5ms	100x faster
HMR	50ms	5ms	10x faster

CSS-First Configuration

No more JavaScript config files. Define your design system in CSS:

@import 'tailwindcss';

@theme {
  /* Colors */
  --color-brand: oklch(65% 0.25 250);
  --color-brand-light: oklch(85% 0.15 250);
  --color-brand-dark: oklch(45% 0.3 250);

  /* Typography */
  --font-display: 'Cal Sans', system-ui;
  --font-body: 'Inter', sans-serif;

  /* Spacing */
  --spacing-gutter: 1.5rem;
  --spacing-section: 4rem;

  /* Breakpoints */
  --breakpoint-tablet: 768px;
  --breakpoint-desktop: 1024px;
  --breakpoint-wide: 1440px;
}

New Container Query Syntax

Native container queries are now first-class:

<div class="@container">
  <div class="@sm:grid-cols-2 @lg:grid-cols-4 grid gap-4">
    <Card />
    <Card />
    <Card />
    <Card />
  </div>
</div>

Composable Variants

Create custom variant combinations:

@variant hocus (&:hover, &:focus);
@variant group-hocus (:merge(.group):hover &, :merge(.group):focus &);
@variant motion-safe (@media (prefers-reduced-motion: no-preference));

Use them in your HTML:

<button class="hocus:bg-brand motion-safe:transition-all">Click me</button>

Automatic Dark Mode

Dark mode now uses light-dark() CSS function:

@theme {
  --color-bg: light-dark(white, #0a0a0a);
  --color-text: light-dark(#171717, #ededed);
}

3D Transform Utilities

New utilities for 3D transforms:

<div class="perspective-1000">
  <div class="rotate-x-45 rotate-y-30 translate-z-20 transform-3d">
    3D transformed element
  </div>
</div>

Migration from v3

Step 1: Update Dependencies

npm install tailwindcss@4

Step 2: Convert Config to CSS

/* From tailwind.config.js to CSS */
@import 'tailwindcss';

@theme {
  --color-primary: #3b82f6;
  /* ... your custom values */
}

Step 3: Update Variants

<!-- v3 -->
<div class="dark:bg-gray-900">
  <!-- v4 (same, but now uses CSS custom properties) -->
  <div class="dark:bg-gray-900"></div>
</div>

Breaking Changes

@apply now uses CSS-native syntax
Arbitrary values use [] consistently
Some legacy utilities removed (see migration guide)

Tailwind v4 is the biggest update since v1.0—faster, more powerful, and more CSS-native than ever.

Posted ontailwindcsswith tags:

#tailwindcss #css #web-development