Tailwind CSS 4 Guide 2026: What's New and How to Migrate

Tailwind CSS 4 dropped earlier this year and it is easily the biggest update the framework has ever seen. The team rebuilt the engine from scratch, replaced the JavaScript config file with pure CSS configuration, and made the whole thing significantly faster.

If you have been using Tailwind 3.x, you will notice differences right away. Some things are simpler now. A few things work differently. This guide covers what actually changed, what you need to update, and how to migrate without breaking your project.

What Changed in Tailwind CSS 4

The short version: almost everything under the hood is new, but your day-to-day utility classes mostly stay the same.

New CSS-First Configuration

The biggest change is that tailwind.config.js is no longer the default way to configure Tailwind. Instead, you write your configuration directly in CSS using @theme directives.

Here is what the old config looked like:

// tailwind.config.js (Tailwind 3)
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: '#6366f1',
      },
    },
  },
  plugins: [],
}

And here is the Tailwind 4 equivalent:

/* globals.css (Tailwind 4) */
@import "tailwindcss";

@theme {
  --color-brand: #6366f1;
  --font-heading: "Inter", sans-serif;
  --breakpoint-3xl: 1920px;
}

Everything lives in your CSS file now. Colors, fonts, spacing, breakpoints - all defined as CSS custom properties inside @theme. This means your config is closer to the actual output and easier to debug in browser dev tools.

Oxide Engine - Much Faster Builds

Tailwind 4 uses a completely new engine (codenamed Oxide) that is written in Rust. The result is dramatic:

• Full builds are up to 10x faster
• Incremental builds (when you save a file) are up to 100x faster
• Hot module replacement feels instant even on large projects

If you have ever waited 2-3 seconds for Tailwind to rebuild on save, those days are over.

Automatic Content Detection

You no longer need a content array in your config. Tailwind 4 automatically detects your template files by scanning your project. It knows where to look for class names without you telling it.

// Tailwind 3 - you needed this
module.exports = {
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
}

/* Tailwind 4 - automatic, no content config needed */
@import "tailwindcss";

Built-in Container Queries

Container queries are now built into Tailwind 4 without needing a plugin:

<div class="@container">
  <div class="@sm:flex @lg:grid @lg:grid-cols-3">
    <!-- Responds to container size, not viewport -->
  </div>
</div>

New Default Color Palette

The color palette got an update. Shades are more consistent, and there is better contrast across light and dark themes. If you relied on specific hex values from Tailwind 3, double-check your designs after upgrading.

How to Migrate from Tailwind 3 to 4

Here is the step-by-step process.

Step 1: Update Dependencies

npm install tailwindcss@latest @tailwindcss/postcss@latest

If you use the typography or forms plugin, update those too:

npm install @tailwindcss/typography@latest

Step 2: Update Your PostCSS Config

// postcss.config.mjs (Tailwind 4)
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

You are replacing tailwindcss and autoprefixer with a single @tailwindcss/postcss plugin.

Step 3: Replace the Config File with CSS

Move your tailwind.config.js customizations into your CSS file. Here is a common migration:

@import "tailwindcss";

@theme {
  --color-primary: #6366f1;
  --color-primary-foreground: #ffffff;
  --color-background: #ffffff;
  --color-foreground: #0f172a;
  --font-sans: "Inter", system-ui, sans-serif;
  --font-mono: "JetBrains Mono", monospace;
}

Step 4: Remove Deprecated Directives

The old @tailwind base, @tailwind components, and @tailwind utilities directives are replaced by a single import:

/* Old (Tailwind 3) */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* New (Tailwind 4) */
@import "tailwindcss";

Step 5: Fix Breaking Class Name Changes

A few utility classes changed:

Step 6: Test Everything

Run your dev server, check every page, and look for visual differences. Most projects migrate cleanly, but custom plugins or unusual configurations might need adjustments.

New Features Worth Using

Variant Groups

Group multiple variants to reduce repetition:

<button class="hover:(bg-blue-500 text-white scale-105)">
  Click me
</button>

3D Transforms

<div class="rotate-x-12 rotate-y-6 perspective-800">
  3D transformed element
</div>

Field Sizing

Auto-resize textareas based on content:

<textarea class="field-sizing-content"></textarea>

Should You Upgrade Right Now?

If you are starting a new project, use Tailwind 4 without question. The CSS-first config, faster builds, and automatic content detection make it the clear choice.

For existing projects, the migration is straightforward for most apps. The official upgrade tool handles a lot of the work:

npx @tailwindcss/upgrade

Run it, review the changes, fix anything it missed, and you should be good.

Related Guides

Using Tailwind 4 with a framework? Check out our React 19 best practices and Next.js deployment guide. If you are new to typed CSS, our TypeScript guide pairs well. And grab the right VS Code extensions for Tailwind IntelliSense.

Keep Reading

If you found this helpful, check out these related guides:

• Build a Portfolio Website
• Website Speed Optimization