Tailwind CSS v4 Migrations-Guide: Neue Features und Anderungen

Tailwind CSS v4 is a ground-up rewrite that delivers significantly faster builds, a simplified configuration experience, and a modern CSS-first approach. Moving from v3 to v4 requires understanding the new architecture, updated configuration patterns, and breaking changes. This comprehensive guide walks you through the migration process with practical examples and best practices.

What Is New in Tailwind CSS v4

Tailwind CSS v4 is not just an incremental update. It is a complete rewrite with a new engine called Oxide, built on Rust for dramatically faster performance. The most visible change is the shift from JavaScript configuration (tailwind.config.js) to CSS-first configuration using @theme directives.

Performance Improvements

The new Oxide engine delivers up to 10x faster full builds and 100x faster incremental builds compared to v3. Hot module replacement (HMR) is nearly instantaneous, even in large projects with thousands of utility classes.

CSS-First Configuration

Tailwind v4 moves configuration into your CSS file using @theme, @variant, and @utility directives. This eliminates the need for tailwind.config.js in most projects and makes the configuration more discoverable and maintainable.

/* Tailwind v4: CSS-first configuration */
@import "tailwindcss";

@theme {
  --color-primary: oklch(0.6 0.2 250);
  --color-secondary: oklch(0.7 0.15 180);
  --font-display: "Inter", sans-serif;
  --font-body: "Source Sans 3", sans-serif;
  --breakpoint-sm: 640px;
  --breakpoint-md: 768px;
  --breakpoint-lg: 1024px;
  --breakpoint-xl: 1280px;
  --radius-lg: 12px;
  --spacing-18: 4.5rem;
}

/* Custom utilities */
@utility text-balance {
  text-wrap: balance;
}

/* Custom variants */
@variant hocus (&:hover, &:focus);
@variant theme-dark (.dark &);

Modern CSS Features

Tailwind v4 leverages modern CSS features including cascade layers (@layer), container queries, anchor positioning, color-mix(), and wide-gamut colors (oklch, oklab). No PostCSS plugin is required for the default setup.

Migration Steps

Follow these steps to migrate your project from Tailwind CSS v3 to v4.

Step 1: Update Dependencies

Install the latest Tailwind CSS v4 package and remove the PostCSS plugin if you are using Vite.

# Run the automated upgrade tool (recommended)
npx @tailwindcss/upgrade

# Or manually update dependencies
npm install tailwindcss@latest

# For Vite projects, install the Vite plugin
npm install @tailwindcss/vite

# Remove the PostCSS plugin (if using Vite)
npm uninstall @tailwindcss/postcss autoprefixer

# vite.config.ts
import tailwindcss from "@tailwindcss/vite";

export default {
  plugins: [tailwindcss()],
};

Step 2: Update Your CSS Entry Point

Replace the @tailwind directives with the new @import syntax. In v4, you import Tailwind as a CSS module.

/* v3 (old) */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* v4 (new) */
@import "tailwindcss";

/* That single import replaces all three directives */
/* Tailwind automatically detects your source files */

Step 3: Migrate tailwind.config.js to CSS

Move your theme customizations from tailwind.config.js into your CSS file using @theme. Most configuration options have direct CSS equivalents.

/* v3: tailwind.config.js */
// module.exports = {
//   theme: {
//     extend: {
//       colors: {
//         brand: '#3b82f6',
//         accent: '#f59e0b',
//       },
//       fontFamily: {
//         display: ['Inter', 'sans-serif'],
//       },
//       spacing: {
//         '18': '4.5rem',
//       },
//     },
//   },
// }

/* v4: CSS configuration */
@import "tailwindcss";

@theme {
  --color-brand: #3b82f6;
  --color-accent: #f59e0b;
  --font-display: "Inter", sans-serif;
  --spacing-18: 4.5rem;
}

/* Use in templates: bg-brand, text-accent, font-display, mt-18 */

Step 4: Update Class Names

Some utility class names have changed in v4. Review your templates for deprecated or renamed classes.

<!-- Renamed utilities in v4 -->

<!-- Shadow color: shadow-[color] -> shadow-[color]/opacity -->
<!-- v3 --> <div class="shadow-lg shadow-blue-500/50">
<!-- v4 --> <div class="shadow-lg shadow-blue-500/50">  <!-- same -->

<!-- Ring offset: ring-offset-2 ring-offset-blue-500 -->
<!-- Now uses outline utilities in some cases -->

<!-- Blur: backdrop-blur-sm -> backdrop-blur-sm  (unchanged) -->

<!-- Gradient stops are the same but color syntax may differ -->
<!-- v3 --> <div class="bg-gradient-to-r from-blue-500 to-purple-500">
<!-- v4 --> <div class="bg-linear-to-r from-blue-500 to-purple-500">

<!-- Content classes renamed -->
<!-- v3 --> <div class="content-center">
<!-- v4 --> <div class="place-content-center">

<!-- Decoration renamed -->
<!-- v3 --> <div class="decoration-2">
<!-- v4 --> <div class="decoration-2">  <!-- unchanged -->

Breaking Changes

Tailwind v4 includes several breaking changes that you need to address during migration.

New Features in v4

Container Queries

Tailwind v4 includes built-in support for CSS container queries, allowing you to style elements based on their parent container size rather than the viewport.

<!-- Container queries in Tailwind v4 -->
<div class="@container">
  <div class="flex flex-col @md:flex-row @lg:grid @lg:grid-cols-3">
    <div class="@sm:p-4 @md:p-6">
      Responds to container width, not viewport
    </div>
  </div>
</div>

<!-- Named containers -->
<div class="@container/sidebar">
  <div class="@md/sidebar:flex-row">
    Content adapts to sidebar width
  </div>
</div>

Color Mixing

New color mixing utilities let you blend colors using CSS color-mix(). This is useful for creating tints, shades, and custom color variations without defining them in your theme.

<!-- Color mixing in v4 -->
<div class="bg-blue-500/50">50% opacity blue</div>
<div class="bg-mix-blue-500-white-30">30% white mixed into blue</div>

/* oklch colors in theme */
@theme {
  --color-brand-50: oklch(0.97 0.02 250);
  --color-brand-100: oklch(0.93 0.04 250);
  --color-brand-500: oklch(0.6 0.2 250);
  --color-brand-900: oklch(0.3 0.15 250);
}

Dark Mode Improvements

Dark mode in v4 uses the CSS prefers-color-scheme media query by default and can be customized using the @variant directive for class-based toggling.

/* Dark mode with system preference (default in v4) */
<div class="bg-white dark:bg-gray-900">
  Automatic dark mode based on OS preference
</div>

/* Class-based dark mode */
@import "tailwindcss";

@variant dark (&:where(.dark, .dark *));

/* Now use: <html class="dark"> to toggle */

Custom Utilities in v4

Tailwind v4 makes creating custom utilities simpler with the @utility directive. You can define utilities directly in CSS without writing a JavaScript plugin.

/* Custom utilities in v4 */
@utility text-balance {
  text-wrap: balance;
}

@utility content-auto {
  content-visibility: auto;
}

@utility scrollbar-hidden {
  scrollbar-width: none;
  &::-webkit-scrollbar {
    display: none;
  }
}

/* Custom utility with variants */
@utility glass {
  background: rgba(255, 255, 255, 0.1);
  backdrop-filter: blur(12px);
  border: 1px solid rgba(255, 255, 255, 0.2);
}

/* Usage in templates */
/* <div class="text-balance glass scrollbar-hidden"> */
/* <div class="hover:glass dark:glass"> */

Quick Reference: v3 to v4 Changes

// Configuration changes summary
// v3: tailwind.config.js    -> v4: @theme in CSS
// v3: @tailwind base         -> v4: @import "tailwindcss"
// v3: content: [...]         -> v4: auto-detection
// v3: plugins: [...]         -> v4: @plugin "..." or @utility

// PostCSS setup
// v3: postcss.config.js with @tailwindcss/postcss
// v4: Vite plugin (recommended) or @tailwindcss/postcss

// Source detection
// v4 automatically scans:
// - All .html, .jsx, .tsx, .vue, .svelte files
// - Ignores node_modules, .git, dist
// - Configure with @source directive if needed:
// @source "../other-project/src/**/*.tsx";

Migration Best Practices

• Run the automated migration tool first: npx @tailwindcss/upgrade
• Migrate one component at a time rather than the entire project at once
• Use the browser DevTools to compare rendered styles before and after migration
• Check for custom plugins and update them to the new API before upgrading
• Test responsive breakpoints thoroughly as the default breakpoint values may differ
• Review color usage since v4 uses oklch color space by default
• Update IDE extensions to the latest versions for v4 autocomplete support

Frequently Asked Questions