Tailwind CSS v4: What's New and How to Migrate
Everything you need to know about Tailwind CSS v4 — the new CSS-first configuration, lightning-fast engine, new utilities, container queries, and step-by-step migration from v3.
What Changed in Tailwind v4?
Tailwind CSS v4 is a ground-up rewrite with a new engine that's up to 10x faster. The biggest change: configuration moves from tailwind.config.js to your CSS file.
Key changes at a glance:
| Feature | v3 | v4 |
|---------|----|----|
| Configuration | tailwind.config.js | CSS @theme directive |
| Build speed | Fast | 10x faster (full builds in ~5ms) |
| Engine | PostCSS plugin | Standalone (Oxide engine) |
| Container queries | Plugin needed | Built-in |
| 3D transforms | Not available | Built-in |
| @apply | Worked | Still works, less needed |
| Color opacity | bg-red-500/50 | Same + P3 wide gamut colors |
Getting Started
New Project
CSS Setup
That's it. No tailwind.config.js, no @tailwind base/components/utilities. One import.
Vite Configuration
Next.js / PostCSS
CSS-First Configuration
The biggest paradigm shift — your theme lives in CSS, not JavaScript.
v3 (Old Way)
v4 (New Way)
Use it exactly the same in HTML:
How @theme Variables Map to Classes
New Utilities in v4
Container Queries
Style elements based on their parent container's size, not the viewport.
Named containers:
3D Transforms
New Color Utilities
Field Sizing
New Variant: inert
not-* Variant
Dark Mode
Or use the built-in dark: variant as before:
Migration from v3 to v4
Step 1: Update Dependencies
Step 2: Update PostCSS Config
Step 3: Update CSS Entry Point
Step 4: Move Config to CSS
Move your tailwind.config.js theme into @theme:
Step 5: Handle Breaking Changes
Step 6: Content Detection
v4 auto-detects your content files — no content array needed. It scans your project automatically (respects .gitignore).
To add extra sources:
Plugins in v4
Official Plugins
Custom Plugin (CSS-based)
Performance
v4's Oxide engine delivers dramatic speed improvements:
v3 v4
Full build: 300ms ~5ms
Incremental: ~100ms <1ms
This is because v4:
- Is written in Rust (via the Oxide engine)
- Scans files in parallel
- Has zero PostCSS overhead when using the Vite plugin
Practical Examples
Responsive Card Grid
Container Query Sidebar
Summary
Tailwind v4 is faster, simpler, and more powerful. The CSS-first approach means less tooling, fewer config files, and a more natural workflow. If you're starting a new project, use v4. If you're on v3, migrate when you have time — the breaking changes are manageable and the performance gains are significant.