Tailwind CSS v4: What's New and Should You Upgrade?

By Eoin Villarin, 2025-12-10, updated 2026-10-28

Tailwind CSS v4 swapped tailwind.config.js for CSS-first config and a rewritten engine, and kept shipping through v4.3. Here is what changed, what breaks and whether to upgrade now.

Tailwind CSS v4 is the biggest change to the framework since it launched. The JavaScript config file is gone by default, the engine was rewritten from scratch, and the way you customise colours, fonts and breakpoints now lives in plain CSS. If you have a v3 project in production, the question is no longer whether v4 is stable. It is whether the upgrade is worth your time right now.

The first v4 release landed in January 2025, and the framework has kept shipping since then. At the time of writing in October 2026 the latest release is v4.3.3, which adds scrollbar styling, size containers and a dedicated webpack loader on top of the original rewrite.

In this guide you will learn what actually changed, which new features are worth using, what breaks when you upgrade, the exact steps I follow to migrate, and how to decide whether your project should move now or wait.

What is new in Tailwind CSS v4?

Version 4.0 shipped on January 22, 2025 as a ground-up rewrite. The headline changes fall into three groups: a much faster engine, configuration that lives in CSS, and a long list of utilities built on modern CSS features like cascade layers, @property and color-mix().

A faster engine with real numbers

The Tailwind team published benchmarks against their Catalyst UI kit in the official v4.0 announcement. Full builds dropped from 378ms to 100ms, incremental rebuilds that add new CSS went from 44ms to 5ms, and incremental rebuilds with no new CSS went from 35ms to 192 microseconds. In day to day work that means hot reload feels instant even on large templates.

Zero configuration content detection

In v3 you had to list every template path in a content array, and forgetting one meant missing styles in production. v4 detects your source files automatically. It respects .gitignore, skips binary files, and lets you add or exclude paths with the @source directive when you need to.

@import "tailwindcss";

/* Scan a UI package that lives in node_modules */
@source "../node_modules/@acme/ui";

/* Ignore a legacy folder you are not migrating yet */
@source not "../src/legacy";

/* Safelist classes that only exist in a CMS */
@source inline("{hover:,}bg-brand-{500,900}");

How does CSS-first configuration with @theme work?

The single biggest mental shift is that your design tokens now live in your stylesheet. Instead of a tailwind.config.js file, you import Tailwind with one line and define tokens inside an @theme block. Each variable namespace maps to a set of utilities, so --color-brand-500 gives you bg-brand-500, text-brand-500 and every other colour utility.

@import "tailwindcss";

@theme {
  --font-display: "Satoshi", sans-serif;
  --color-brand-500: oklch(0.62 0.21 285);
  --color-brand-900: oklch(0.28 0.09 280);
  --breakpoint-3xl: 120rem;
  --ease-snappy: cubic-bezier(0.2, 0, 0, 1);
}

That block gives you font-display, bg-brand-900, a 3xl: breakpoint variant and ease-snappy with no extra setup.

Theme values are real CSS variables

Every token is also emitted as a native CSS custom property. That means you can read var(--color-brand-500) in a plain stylesheet, animate it with a JavaScript library, or override it inside a scoped section for a dark theme. In v3 you needed the theme() function or resolveConfig for this, and the latter has been removed.

Custom utilities, variants and plugins

Because v4 uses native cascade layers, the old trick of adding classes inside @layer utilities is replaced with explicit directives:

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

@custom-variant theme-midnight (&:where([data-theme="midnight"] *));

@plugin "@tailwindcss/typography";

Custom utilities declared this way work with every variant, so hover:content-auto and md:content-auto behave exactly like built-in classes. If you maintain a component library, my guide to building a design system with React and Storybook shows how tokens like these feed into shared components.

Which new features are worth using?

Not every new utility will change how you work, but a handful replace custom CSS in most projects:

• Container queries in core. Mark a parent with @container and use @sm:, @lg: or @max-md: on children. No plugin required.
• Dynamic values. Utilities like grid-cols-15, mt-17 or data-current:opacity-100 work without configuration or square brackets.
• 3D transforms. rotate-x-*, rotate-y-*, perspective-* and transform-3d cover card flips and depth effects.
• Expanded gradients. bg-linear-45, bg-radial and bg-conic with interpolation modifiers such as /oklch.
• Enter transitions. The starting: variant uses @starting-style to animate elements as they appear, with no JavaScript.
• Modern defaults. The colour palette moved to OKLCH for more vivid P3 colours, and utilities like field-sizing-content, inert and not-* are built in.

What v4.1, v4.2 and v4.3 added since launch

The point releases have been substantial. v4.1 (April 2025) added text-shadow-* and mask-* utilities, coloured drop shadows, pointer-fine and pointer-coarse variants, user-valid and user-invalid for friendlier form validation, plus @source not and @source inline(). v4.2 (February 2026) added four new neutral palettes, more logical property utilities and the @tailwindcss/webpack loader. The Tailwind team measured it at over 2x faster than the PostCSS route on their own Next.js docs site.

v4.3 (May 2026) added first-party scrollbar utilities like scrollbar-thin and scrollbar-thumb-*, an @container-size utility for size containers, and new zoom-* and tab-* utilities. The v4.3 release post covers both v4.2 and v4.3 in detail.

What breaks when you upgrade from Tailwind v3?

Most breaking changes are renames or new defaults. They are easy to fix once you know about them, but they are also the reason a "quick" upgrade can leave subtle visual bugs behind. These are the ones I check on every project:

The space-y-* and divide-* utilities also use a new selector for performance, which can change spacing on inline elements. Buttons now use cursor: default, and the placeholder colour changed. The full list is in the official Tailwind upgrade guide.

How to upgrade to Tailwind CSS v4 step by step

This is the process I use for client projects. On a typical marketing site or mid-size app it takes a few hours, and most of that time goes into visual review rather than code changes.

1. Create a branch and make sure your environment runs Node.js 20 or higher, which the upgrade tool requires.
2. Run the official tool with npx @tailwindcss/upgrade. It updates dependencies, migrates your JavaScript config into CSS and rewrites renamed classes in your templates.
3. Switch build plugins. PostCSS projects use @tailwindcss/postcss, Vite projects should use @tailwindcss/vite, and webpack projects can use @tailwindcss/webpack. You can remove autoprefixer and postcss-import.
4. Review the diff file by file. Pay close attention to dynamic class names built from strings, since no tool can rewrite those reliably.
5. Fix component-scoped styles. CSS modules and Vue or Svelte <style> blocks need @reference "../app.css" before they can use @apply with your theme.
6. Compare every key template in the browser at mobile and desktop widths, ideally with screenshot tests.

If your config is too complex to migrate in one go, you can keep it and load it explicitly while you move tokens across gradually:

@import "tailwindcss";
@config "../../tailwind.config.js";

Note that the corePlugins, safelist and separator options are not supported in v4. Safelisting moves to @source inline(). If you are also changing build tools at the same time, my comparison of Vite and webpack explains which one I would pick for a new project.

Browser support: who should stay on v3.4?

This is the one hard blocker. Tailwind CSS v4 is designed for Safari 16.4+, Chrome 111+ and Firefox 128+. It depends on @property and color-mix() for core features, so it will not degrade gracefully in older browsers. The Tailwind team recommends staying on v3.4 if you need to support anything older.

Check your analytics before you check your codebase. If a meaningful share of paying customers use browsers older than Safari 16.4, the upgrade can wait no matter how fast the new engine is.

For most consumer sites in 2026 those versions cover the vast majority of traffic. Enterprise intranets, kiosk hardware and embedded webviews are where I still find older engines, so check before you commit.

Should you upgrade to Tailwind CSS v4 now?

Here is how I advise clients, based on the type of project:

• New projects: start on v4. There is no reason to begin on v3 in 2026, and the CSS-first setup is simpler to learn.
• Active small and mid-size projects: upgrade in a dedicated branch. The faster builds and modern utilities pay for the effort quickly.
• Large design systems with heavy JavaScript config: use @config to upgrade the engine first, then migrate tokens to @theme over several releases.
• Projects that must support old browsers: stay on v3.4 until your analytics say otherwise.
• Sites that rarely change: there is little benefit in touching a stable build. Upgrade when you next do significant front-end work.

Once you are on v4, pair it with modern layout features. My guides to CSS subgrid and view transitions and anchor positioning show what native CSS can now handle without extra libraries.

Frequently asked questions

Is Tailwind v4 backward compatible with v3 classes?

Mostly, but not completely. The vast majority of class names are unchanged, yet several sizes were renamed, such as shadow-sm becoming shadow-xs, and defaults for borders and rings changed. The official upgrade tool rewrites most of these automatically, but you should still review the diff and compare pages visually before you merge.

Do I still need tailwind.config.js in v4?

No. New projects configure everything in CSS with @theme, @utility, @custom-variant and @plugin. JavaScript config files are still supported for backward compatibility, but they are no longer detected automatically, so you must load one explicitly with the @config directive if you want to keep it during a gradual migration.

How long does a Tailwind v4 upgrade take?

For a typical business website or mid-size app, expect a few hours to a day. The automated tool handles most code changes in minutes. The remaining time goes into reviewing dynamic class names, fixing component-scoped styles and checking each key template visually. Large design systems with custom plugins can take longer and are best migrated in stages.

Does Tailwind v4 work with Next.js and Vite?

Yes. Vite projects should use the first-party @tailwindcss/vite plugin. Next.js works with @tailwindcss/postcss, and since v4.2 the @tailwindcss/webpack loader is an option too, which Tailwind measured as more than twice as fast on a large Next.js site. Both setups need only a single @import "tailwindcss" in your stylesheet.

Next steps: plan your upgrade

Tailwind v4 is mature, fast and pleasant to work with, and v4.3 has filled most of the gaps that held teams back in early 2025. For new work it is the obvious choice. For existing projects, check your browser data, run the upgrade tool in a branch and budget time for visual review rather than code changes.

If you would rather have someone handle the migration, or you want a front-end rebuild done properly, get in touch through my contact form. You can also browse my web development case studies to see the kind of sites and apps I build for clients.