Tailwind CSS v4

What Changed in v4

Tailwind CSS v4 is a ground-up rewrite with a new high-performance engine built on Lightning CSS. Configuration moves from JavaScript to CSS using @theme, @utility, and @source directives. Many v3 plugins are now built-in.

The v4 engine is 3–5x faster than v3 for full builds and 100x+ faster for incremental builds with no new CSS. Automatic content detection eliminates the content array.

• v4 uses native CSS cascade layers for proper specificity
• Automatic content detection scans project files without config
• Lightning CSS handles nesting, autoprefixer, and minification

/* v4 entry point — no tailwind.config.js needed */
@import "tailwindcss";

@theme {
  --color-brand: #2563eb;
  --font-sans: 'Inter', system-ui, sans-serif;
}

CSS-First Configuration

Define design tokens as CSS custom properties in @theme. Tailwind generates utilities from these variables automatically. --color-brand creates bg-brand, text-brand, border-brand, and all color utilities.

Override defaults by redefining theme variables. Add new tokens by declaring new custom properties. The @theme block replaces theme.extend in JavaScript config.

@import "tailwindcss";

@theme {
  --color-brand-50: #eff6ff;
  --color-brand-500: #2563eb;
  --color-brand-900: #1e3a8a;
  --spacing-18: 4.5rem;
  --breakpoint-3xl: 1920px;
}

New Built-in Features

Container queries, 3D transforms, enhanced gradients, @starting-style for entry animations, and not-* variants are built into v4 without plugins. The not-* variant applies styles when a condition is false.

Dynamic utility values use CSS variables directly. Size-* utilities unify width and height. Color-mix support enables opacity without slash syntax.

<!-- Built-in container queries -->
<div class="@container">
  <div class="grid grid-cols-1 @lg:grid-cols-2">...</div>
</div>

<!-- 3D transforms -->
<div class="perspective-distant transform-3d rotate-x-12">

Vite and PostCSS Setup

Install @tailwindcss/vite for Vite projects or @tailwindcss/postcss for PostCSS pipelines. Remove tailwindcss, autoprefixer, and postcss from v3 setup — v4 handles prefixing internally.

Next.js projects add @tailwindcss/postcss to postcss.config.mjs. Replace @tailwind directives with @import "tailwindcss" in globals.css.

// vite.config.ts
import tailwindcss from '@tailwindcss/vite';
export default { plugins: [tailwindcss()] };

// postcss.config.mjs (Next.js)
export default { plugins: { '@tailwindcss/postcss': {} } };

Migrating from v3

Run npx @tailwindcss/upgrade for automated migration. Key changes: replace tailwind.config.js with @theme CSS, update @tailwind directives to @import, remove autoprefixer and postcss plugins, update deprecated utilities.

Some v3 plugins become unnecessary (container-queries, aspect-ratio). Custom plugins may need rewriting for the v4 plugin API. Test thoroughly — utility names and defaults changed.

• Run the upgrade tool on a branch — review all changes
• v4 requires modern browsers (Safari 16.4+, Chrome 111+)
• Keep v3 for projects needing older browser support

# Automated migration tool
npx @tailwindcss/upgrade

# Key renames:
# flex-shrink-0 → shrink-0
# overflow-ellipsis → text-ellipsis
# shadow-sm → shadow-xs (scale shifted)