Overview
Tailwind CSS v4 is a complete rewrite of the framework, built on a new Rust-based Oxide engine that's 10x faster. The biggest change: configuration is now done in CSS, not JavaScript. No more tailwind.config.js for most projects.
Browser support: Safari 16.4+, Chrome 111+, Firefox 128+
The Oxide Engine (Performance)
Tailwind v4 uses a new Rust-based Oxide engine with dramatically improved performance:
| Operation | v3 Speed | v4 Speed (Oxide) | Improvement |
|---|---|---|---|
| Cold build | 8s | 2.1s | 3.78x faster |
| Incremental | 450ms | 51ms | 8.8x faster |
| HMR (Hot Module Reload) | 350ms | 12ms | 28x faster |
| Memory usage | Higher | Lower | ~50% reduction |
Why It's Faster
- Rust-native: Core processing in Rust, not JavaScript
- Parallel processing: Uses all CPU cores efficiently
- Better caching: Improved incremental build detection
- Optimized CSS generation: Less overhead in utility generation
Requirements
# Node.js 18+ required for Oxide engine
node --version # Should be 18 or higher
Installation
Vite (Recommended)
npm install tailwindcss @tailwindcss/vite
// vite.config.js
import tailwindcss from "@tailwindcss/vite";
export default {
plugins: [tailwindcss()],
};
PostCSS
npm install -D tailwindcss @tailwindcss/postcss
// postcss.config.js
export default {
plugins: {
"@tailwindcss/postcss": {},
},
};
CLI
npm install -D @tailwindcss/cli
npx @tailwindcss/cli -i input.css -o output.css --watch
Basic Setup
The CSS File
/* input.css */
@import "tailwindcss";
/* Your custom styles below */
That's it. No @tailwind base/components/utilities directives—they're gone.
Dark Mode
In v4, dark mode uses @media (prefers-color-scheme) by default—no config needed.
<!-- Automatically responds to OS preference -->
<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">
Hello, dark mode!
</div>
For manual toggle, add .dark class to <html> element:
<html class="dark">
<div class="bg-white dark:bg-gray-900">...</div>
</html>
No darkMode config option needed—it just works.
Arbitrary Values
CSS Variables (New Syntax)
Variables now use parentheses, not brackets:
<!-- v3 -->
<div class="bg-[--brand-color]">
<!-- v4 -->
<div class="bg-(--brand-color)">
Grid Values
Use underscores for spaces, not commas:
<!-- v3 -->
<div class="grid-cols-[max-content,auto]">
<!-- v4 -->
<div class="grid-cols-[max-content_auto]">
The Important Modifier
The ! now goes at the end of the utility:
<!-- v3 -->
<div class="!bg-red-500">
<!-- v4 -->
<div class="bg-red-500!">
Both work in v4, but the new syntax is preferred.
Automatic Content Detection
No more content array in config. Tailwind v4 automatically scans for classes in your project.
Backward Compatibility with @config
Need to keep your old tailwind.config.js? Use @config:
@import "tailwindcss";
@config "../../tailwind.config.js";
Note: corePlugins, safelist, and separator options are not supported in v4.
Framework Integration
In v4, styles in separate files (Vue <style>, Svelte, CSS modules) don't see theme variables by default. Use @reference:
<template>
<h1>Hello</h1>
</template>
<style>
@reference "../app.css";
h1 {
@apply text-2xl font-bold text-red-500;
}
</style>
Common Issues and Solutions
Missing classes after build
- Run
npx @tailwindcss/upgradeto set up v4 correctly - Ensure CSS is processed by the v4 plugin
Dark mode not applying
- Use automatic mode (no config needed in v4)
- Add
class="dark"to<html>for manual toggle
Custom utilities not working
- Use
@utilitydirective instead of@layer utilities - Ensure the CSS file with
@themedefinitions is imported
Performance issues
- v4 is 10x faster with the Oxide engine
- Ensure you're using the latest
@tailwindcss/viteor@tailwindcss/postcss
Prefix changes
Prefixes now work like variants—always at the beginning:
<div class="tw:flex tw:bg-red-500 tw:hover:bg-red-600">
Best Practices
Do:
- Use
@themefor all custom design tokens - Use
@utilityfor reusable patterns - Leverage the CSS variables (
var(--color-*)) in JavaScript - Let dark mode be automatic
- Use
@configonly for legacy projects
Don't:
- Create a
tailwind.config.jsfor new projects - Use Sass/Less/Stylus—they don't work with v4
- Use the old
theme()function—use CSS variables instead - Use brackets for CSS variables—use parentheses:
bg-(--var)
Migration Checklist
- Run
npx @tailwindcss/upgrade - Replace
@tailwinddirectives with@import "tailwindcss" - Convert
tailwind.config.jsto@themein CSS - Replace
ringwithring-3 - Replace
shadowwithshadow-sm,shadow-smwithshadow-xs - Replace
outline-nonewithoutline-hidden - Add explicit border colors where needed
- Update variant stacking order
- Update arbitrary value syntax (
[...]→(...)) - Update grid syntax (
,→_) - Move
!to end of utility for important - Test dark mode
- Verify custom utilities work with
@utility - Update Vue/Svelte components with
@referenceif needed
Deep Dives
Load these reference files for detailed information:
- Theme Configuration —
@themedirective syntax, design tokens, colors, spacing, breakpoints, animations —references/theme.md - Custom Utilities & Variants —
@utility,@variantdirectives, utility classes reference —references/utilities-variants.md - Migration from v3 — Breaking changes, upgrade tool, new features, Preflight changes —
references/migration-v4.md