Tailwind CSS v4 Complete Guide 2026: New Features and Migration

⏱️6 min read · 1,183 words

Tailwind CSS v4 is a ground-up rewrite that drops the config file, goes all-in on CSS variables, and delivers a Rust-powered build engine that’s 100x faster than Tailwind v3. In 2026, Tailwind v4 is the default choice for utility-first CSS. This guide covers everything new and how to migrate.

📋 Table of Contents

What Changed in Tailwind v4
Installation
Configuration with @theme
Responsive Design
Container Queries (Built-in in v4)
Dark Mode
New Utilities in v4
Real Component Examples
Migrating from Tailwind v3
Tailwind v4 with React/Next.js

What Changed in Tailwind v4

No tailwind.config.js — configuration moves to CSS using @theme
CSS-native design tokens — all values exposed as CSS custom properties
New Oxide engine — built in Rust, 100x faster, zero-config
CSS @import first — single CSS file import, no PostCSS config needed
Container queries built-in — no plugin needed
New 3D transform utilities — rotate-x, rotate-y, perspective
Color palette rework — oklch-based colors for better gamut

Installation

# Install
npm install tailwindcss @tailwindcss/vite

# Vite config
# vite.config.ts
import tailwindcss from '@tailwindcss/vite'

export default {
  plugins: [tailwindcss()]
}

# Your main CSS file
# app.css
@import "tailwindcss";

Configuration with @theme

No more tailwind.config.js — configure in CSS:

/* app.css */
@import "tailwindcss";

@theme {
  /* Custom colors */
  --color-brand: oklch(60% 0.25 250);
  --color-brand-dark: oklch(40% 0.25 250);
  --color-surface: oklch(98% 0 0);

  /* Custom fonts */
  --font-sans: 'Inter', sans-serif;
  --font-mono: 'JetBrains Mono', monospace;

  /* Custom spacing */
  --spacing-18: 4.5rem;
  --spacing-22: 5.5rem;

  /* Custom breakpoints */
  --breakpoint-3xl: 1920px;

  /* Custom animation */
  --animate-fade-in: fade-in 0.3s ease;
}

@keyframes fade-in {
  from { opacity: 0; transform: translateY(-8px); }
  to   { opacity: 1; transform: translateY(0); }
}

/* CSS variables automatically available as utilities:
   bg-brand, text-brand, border-brand-dark,
   font-sans, animate-fade-in etc. */

Responsive Design

<!-- Mobile-first responsive grid -->
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-6">
  <div class="rounded-xl bg-white p-6 shadow-sm">Card</div>
</div>

<!-- Responsive text -->
<h1 class="text-2xl md:text-4xl lg:text-6xl font-bold">
  Headline
</h1>

<!-- Show/hide at breakpoints -->
<nav class="hidden md:flex gap-6">Desktop Nav</nav>
<button class="md:hidden">Menu</button>

<!-- Arbitrary breakpoints -->
<div class="[@media(min-width:900px)]:flex">Custom breakpoint</div>

Container Queries (Built-in in v4)

<!-- No plugin needed! -->
<div class="@container">
  <div class="@sm:flex @md:grid @md:grid-cols-2 gap-4">
    <!-- Layout changes based on CONTAINER size, not viewport -->
    <div>Item 1</div>
    <div>Item 2</div>
  </div>
</div>

Dark Mode

<!-- Auto dark mode (prefers-color-scheme) -->
<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
  <p class="text-gray-600 dark:text-gray-300">Content</p>
</div>

/* Manual dark mode via data attribute */
@variant dark (&:where([data-theme="dark"] *));

/* Usage: <html data-theme="dark"> */

New Utilities in v4

<!-- 3D Transforms (new in v4) -->
<div class="perspective-500 rotate-x-12 rotate-y-12">3D Card</div>

<!-- Field sizing (auto-resize textarea) -->
<textarea class="field-sizing-content">
  Auto-resizes as you type
</textarea>

<!-- Color mix utilities -->
<div class="bg-blue-500/50">50% transparent blue</div>

<!-- CSS grid improvements -->
<div class="grid grid-cols-[auto_1fr_auto]">
  <div>Left</div>
  <div>Center (fills space)</div>
  <div>Right</div>
</div>

<!-- Starting style (entry animations) -->
<dialog class="starting:opacity-0 starting:scale-95 transition-all">
  Animates in from invisible
</dialog>

Real Component Examples

<!-- Navigation bar -->
<nav class="fixed top-0 inset-x-0 z-50 bg-white/80 backdrop-blur-md border-b border-gray-200">
  <div class="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
    <div class="flex h-16 items-center justify-between">
      <a href="/" class="text-xl font-bold text-gray-900">TechPulse</a>
      <div class="hidden md:flex items-center gap-6">
        <a href="/blog" class="text-sm text-gray-600 hover:text-gray-900 transition-colors">Blog</a>
        <a href="/about" class="text-sm text-gray-600 hover:text-gray-900 transition-colors">About</a>
        <a href="/contact" class="rounded-full bg-blue-600 px-4 py-1.5 text-sm font-medium text-white hover:bg-blue-700 transition-colors">
          Get Started
        </a>
      </div>
    </div>
  </div>
</nav>

<!-- Card component -->
<article class="group rounded-2xl bg-white shadow-sm hover:shadow-md transition-shadow overflow-hidden">
  <div class="aspect-video overflow-hidden">
    <img src="..." alt="..." class="w-full h-full object-cover group-hover:scale-105 transition-transform duration-300">
  </div>
  <div class="p-6">
    <span class="text-xs font-medium text-blue-600 uppercase tracking-wide">Tutorial</span>
    <h2 class="mt-2 text-xl font-semibold text-gray-900 line-clamp-2">Article Title</h2>
    <p class="mt-2 text-gray-600 text-sm line-clamp-3">Article excerpt text goes here.</p>
    <div class="mt-4 flex items-center gap-3">
      <img src="avatar.jpg" alt="Author" class="size-8 rounded-full">
      <div>
        <p class="text-sm font-medium text-gray-900">Alice Chen</p>
        <p class="text-xs text-gray-500">May 29, 2026</p>
      </div>
    </div>
  </div>
</article>

Migrating from Tailwind v3

# Run upgrade tool
npx @tailwindcss/upgrade@next

# Changes:
# - tailwind.config.js → @theme in CSS
# - PostCSS config removed
# - @apply still works but prefer utilities
# - theme() fn → use CSS vars directly
# - Some utility names changed (e.g., shadow-sm → shadow-xs)

# Check migration guide at tailwindcss.com/docs/upgrade-guide

Tailwind v4 with React/Next.js

// components/Button.tsx
import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '@/lib/utils';

const button = cva(
  'inline-flex items-center justify-center rounded-lg font-medium transition-colors focus-visible:outline-none focus-visible:ring-2',
  {
    variants: {
      variant: {
        primary: 'bg-blue-600 text-white hover:bg-blue-700',
        secondary: 'bg-gray-100 text-gray-900 hover:bg-gray-200',
        destructive: 'bg-red-600 text-white hover:bg-red-700',
        ghost: 'hover:bg-gray-100 text-gray-700',
      },
      size: {
        sm: 'h-8 px-3 text-sm',
        md: 'h-10 px-4 text-sm',
        lg: 'h-12 px-6 text-base',
      },
    },
    defaultVariants: { variant: 'primary', size: 'md' },
  }
);

interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof button> {}

export function Button({ className, variant, size, ...props }: ButtonProps) {
  return <button className={cn(button({ variant, size }), className)} {...props} />;
}

Tailwind CSS v4 removes friction — no config file, faster builds, CSS-native tokens. If you are on v3, run the upgrade codemod and move to CSS-based configuration. For new projects, use v4 from day one with the Vite plugin for zero-config setup.

📚 You might also like

🔗 Share this article

X / Twitter Facebook WhatsApp LinkedIn Telegram