Tailwind Version 4

Version 4 is a major update that changes how you install, configure, and write Tailwind. The utility class idea stays the same. The setup around it becomes shorter, faster, and closer to plain CSS. Understanding the changes helps you read both old tutorials and new projects without confusion.

Big Changes at a Glance

Area                Version 3                 Version 4
──────────────────────────────────────────────────────────────
Setup in CSS        three @tailwind lines     @import "tailwindcss";
Configuration       tailwind.config.js        @theme block in CSS
File scanning       content array in config   automatic detection
Build engine        JavaScript                new faster engine
Colors              rgb and hsl               oklch color space

One Line of CSS

Older projects loaded Tailwind with three directives. Version 4 replaces them with one import statement.

/* Version 3 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* Version 4 */
@import "tailwindcss";

CSS-First Configuration

A JavaScript config file is no longer required. You define custom colors, fonts, and sizes inside your CSS file with the @theme directive. Each value becomes a CSS variable that any part of the page can read.

@import "tailwindcss";

@theme {
  --color-brand: #0ea5e9;
  --font-display: "Poppins", sans-serif;
  --breakpoint-3xl: 120rem;
}

Result: classes bg-brand, font-display, and 3xl: now exist.

Automatic Content Detection

Tailwind scans your project files on its own. It ignores files listed in your .gitignore and skips binary files. You no longer maintain a list of template paths. Add a @source directive only when a folder falls outside the automatic scan.

Installing Through a Build Tool

Version 4 ships a dedicated plugin for Vite and a separate package for PostCSS. The Vite route needs the least setup.

npm install tailwindcss @tailwindcss/vite

// vite.config.js
import tailwindcss from "@tailwindcss/vite";
export default { plugins: [tailwindcss()] };

Renamed Utilities

Several small sizes shifted down one step to make room for a new smallest size. Check the table when you upgrade an older project.

Version 3 name     Version 4 name
─────────────────────────────────
shadow-sm          shadow-xs
shadow             shadow-sm
rounded-sm         rounded-xs
rounded            rounded-sm
blur-sm            blur-xs
outline-none       outline-hidden
bg-gradient-to-r   bg-linear-to-r

The old opacity helpers such as bg-opacity-50 no longer exist. Use the slash form bg-black/50 instead.

New Abilities

Dynamic Values

Utilities accept many numbers without extra setup. Classes such as grid-cols-15 and w-17 work immediately.

Container Queries

Container query variants such as @md: arrive built in. No plugin is required.

New Variants

Variants like not-hover:, nth-3:, inert:, and starting: cover cases that once needed arbitrary selectors.

Modern CSS Under the Hood

Generated styles use cascade layers, registered custom properties, and the color-mix function. These features give smoother gradients and more predictable style order.

Why These Changes Help

Simpler setup saves time on every new project. A single import line replaces three directives, and automatic scanning removes a common source of missing styles. Teams no longer wonder why a class has no effect because a folder was absent from the content list.

CSS variables also open new doors. Every theme value lives in the page as a variable, so plain CSS, inline styles, and JavaScript libraries can read the same colors and spacing that your classes use. A chart library can pull var(--color-brand) and match your design without copying a hex code.

:root variables created by @theme
──────────────────────────────────
--color-brand      →  used by bg-brand, text-brand
--spacing          →  base unit behind p-4, m-2
--font-display     →  used by font-display

Learners benefit as well. The configuration lives in the same file as the styles, so one place explains the whole design. Reading a project becomes easier for newcomers.

Browser Support

Version 4 targets modern browsers: Safari 16.4 or newer, Chrome 111 or newer, and Firefox 128 or newer. Projects that must support older browsers stay on version 3.4.

Upgrading an Existing Project

An official upgrade tool handles most of the work. It updates dependencies, converts the config file, and renames changed classes. Run it on a clean Git branch so you can review each change.

npx @tailwindcss/upgrade

The tool requires Node.js 20 or newer. Read the result carefully, test the main pages in a browser, and fix leftovers by hand. Small projects often finish in minutes.

Which Version Should You Learn

Learn the version 4 style for new projects. The class names you practice carry over to version 3 with only a few renamed utilities. A learner who knows both can maintain any Tailwind site.