Tailwind CSS 4.0 is a ground-up rewrite that delivers dramatic performance improvements, a simplified configuration model, and powerful new utilities. The new Oxide engine, written in Rust, compiles stylesheets up to 10x faster than v3. Configuration moves from JavaScript files to native CSS, content detection is automatic, and dozens of new utilities make common patterns easier to implement. This guide covers the most impactful changes with hands-on code examples.
Installation and the New CSS-Based Configuration
Tailwind 4.0 simplifies installation to a single import. No more tailwind.config.js for most projects. Configuration lives directly in your CSS file using the @theme directive.
npm install tailwindcss @tailwindcss/viteFor Vite-based projects, add the plugin to your config.
// vite.config.ts
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'
export default defineConfig({
plugins: [
tailwindcss(),
],
})Your main CSS file replaces the old @tailwind directives with a single import and uses @theme for customization.
/* app.css */
@import "tailwindcss";
@theme {
--color-brand: #6366f1;
--color-brand-light: #818cf8;
--color-brand-dark: #4f46e5;
--color-surface: #f8fafc;
--color-surface-dark: #1e293b;
--font-heading: "Inter", sans-serif;
--font-body: "Source Sans 3", sans-serif;
--breakpoint-xs: 30rem;
--animate-fade-in: fade-in 0.5s ease-out;
--animate-slide-up: slide-up 0.4s ease-out;
}
@keyframes fade-in {
from { opacity: 0; }
to { opacity: 1; }
}
@keyframes slide-up {
from { opacity: 0; transform: translateY(1rem); }
to { opacity: 1; transform: translateY(0); }
}The @theme directive defines design tokens as CSS custom properties. Every token automatically generates corresponding utility classes. Setting --color-brand: #6366f1 creates bg-brand, text-brand, border-brand, and every other color utility.
Zero-Config Content Detection and the Oxide Engine
Tailwind 4.0 eliminates the content array from configuration. The new Oxide engine automatically detects template files in your project by scanning for known file extensions (HTML, JSX, TSX, Vue, Svelte, and more). If you need to include additional sources, use the @source directive.
/* Include files from a specific path */
@source "../components/**/*.php";
@source "../node_modules/my-ui-lib/dist/**/*.js";
/* Exclude a path from scanning */
@source not "../legacy/";The Oxide engine, built in Rust, delivers massive performance gains. Build times drop from seconds to milliseconds on large projects. The engine uses an incremental compilation model — when you change a single file, only the affected utilities are recompiled rather than the entire stylesheet.
For projects that still need a JavaScript configuration file, Tailwind 4.0 supports a compatibility layer.
/* app.css */
@import "tailwindcss";
@config "../tailwind.config.js";New and Redesigned Utility Classes
Tailwind 4.0 introduces several new utilities and refines existing ones. Container queries, 3D transforms, and gradient improvements are among the highlights.
Container queries let components respond to their parent’s size rather than the viewport, which is essential for reusable widget components.
<!-- Container query example -->
<div class="@container">
<div class="flex flex-col @md:flex-row gap-4 p-4">
<img src="product.jpg" class="w-full @md:w-48 rounded-lg object-cover" />
<div>
<h3 class="text-lg @md:text-xl font-semibold">Product Title</h3>
<p class="text-gray-600 mt-1 @md:mt-2">Product description goes here.</p>
<span class="text-brand font-bold text-xl mt-2 block">$29.99</span>
</div>
</div>
</div>The new color system uses the OKLCH color space, providing perceptually uniform colors that look consistent across different hues. You can now use opacity modifiers directly in any color utility.
<!-- Color opacity modifiers -->
<div class="bg-brand/20 text-brand-dark border border-brand/40 rounded-xl p-6">
<p class="text-surface-dark/80">Semi-transparent elements using opacity modifiers.</p>
</div>
<!-- Gradient improvements -->
<div class="bg-linear-to-br from-brand via-purple-500 to-pink-500 text-white p-8 rounded-2xl">
<h2 class="text-3xl font-bold">Enhanced Gradients</h2>
<p class="mt-2 text-white/80">Linear, radial, and conic gradients with interpolation control.</p>
</div>
<!-- Conic gradient -->
<div class="size-32 rounded-full bg-conic from-brand via-pink-500 to-brand"></div>Building Components with Tailwind 4.0
Here is a complete card component using the new features: container queries, the @theme tokens, and improved variant syntax.
<!-- Feature card component -->
<div class="@container group">
<article class="bg-white dark:bg-surface-dark rounded-2xl shadow-md
hover:shadow-xl transition-shadow duration-300
overflow-hidden">
<div class="relative">
<img src="feature.jpg"
class="w-full h-48 @lg:h-64 object-cover
group-hover:scale-105 transition-transform duration-500" />
<span class="absolute top-3 right-3 bg-brand text-white text-xs
font-semibold px-3 py-1 rounded-full">
New
</span>
</div>
<div class="p-5 @lg:p-8">
<h3 class="text-xl @lg:text-2xl font-bold text-gray-900
dark:text-white font-heading">
Feature Title
</h3>
<p class="mt-2 text-gray-600 dark:text-gray-300 font-body
leading-relaxed line-clamp-3">
Description of this feature with enough text to demonstrate
the line-clamp utility that truncates after three lines.
</p>
<div class="mt-4 flex items-center justify-between">
<a href="#" class="text-brand hover:text-brand-dark font-semibold
transition-colors">
Learn more →
</a>
<span class="text-sm text-gray-400">5 min read</span>
</div>
</div>
</article>
</div>For forms, Tailwind 4.0 includes improved focus and validation state utilities.
<!-- Form with validation states -->
<form class="max-w-md mx-auto space-y-4">
<div>
<label class="block text-sm font-medium text-gray-700 mb-1">Email</label>
<input type="email"
class="w-full px-4 py-2.5 rounded-lg border border-gray-300
focus:outline-none focus:ring-2 focus:ring-brand/50 focus:border-brand
invalid:border-red-500 invalid:ring-red-500/50
transition-all placeholder:text-gray-400"
placeholder="you@example.com" />
</div>
<div>
<label class="block text-sm font-medium text-gray-700 mb-1">Password</label>
<input type="password"
class="w-full px-4 py-2.5 rounded-lg border border-gray-300
focus:outline-none focus:ring-2 focus:ring-brand/50 focus:border-brand
transition-all placeholder:text-gray-400"
placeholder="Minimum 8 characters" />
</div>
<button type="submit"
class="w-full py-2.5 bg-brand hover:bg-brand-dark active:bg-brand-dark/90
text-white font-semibold rounded-lg transition-colors
focus:outline-none focus:ring-2 focus:ring-brand/50 focus:ring-offset-2">
Sign In
</button>
</form>Migration Tips and Performance Gains
Migrating from Tailwind 3 to 4 involves several key changes. The official migration tool handles most of the work automatically.
npx @tailwindcss/upgradeKey breaking changes to be aware of:
/* v3 syntax => v4 syntax */
/* @apply in components: still works identically */
.btn-primary {
@apply bg-brand text-white px-6 py-2.5 rounded-lg font-semibold
hover:bg-brand-dark transition-colors;
}
/* Dark mode: now uses the CSS prefers-color-scheme by default */
/* To use class-based dark mode: */
@variant dark (&:where(.dark, .dark *));
/* Custom screens: use --breakpoint tokens */
@theme {
--breakpoint-3xl: 120rem;
}Performance benchmarks tell the story. On a project with 25,000 utility classes, Tailwind 4.0 compiles the full stylesheet in under 100 milliseconds — compared to 800 milliseconds with v3. Incremental rebuilds during development complete in single-digit milliseconds. The CSS output is also smaller thanks to improved deduplication and dead code elimination in the Oxide engine. Tailwind 4.0 is the biggest leap forward since the framework’s initial release, and upgrading is well worth the effort.
