Upgrading from v3 to v4

This section documents Tailwind CSS v4.x — the CSS-first configuration line, whose v4.0 release shipped in January 2025 — as published at the official Tailwind CSS documentation, which is the reference these pages are written and verified against. No specific patch version is pinned.

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production, since Tailwind iterates quickly.

This section’s bibliography lists the reference material consulted while preparing these pages.

Tailwind v4 (January 2025) rewrote the engine and moved configuration into CSS. Most utility names carry over, so v3 knowledge still applies — but the setup, several defaults, and a handful of class names changed. Both books in this section’s bibliography target v3.x; this page is the translation layer. The authoritative list is the Upgrade guide.

The automated tool

npx @tailwindcss/upgrade   # needs Node 20+; run on a clean git branch and review the diff

It migrates the config, the @tailwind directives, renamed classes, and most template changes. Complex projects still need a manual pass.

Configuration

v3 v4

tailwind.config.js (theme, content, plugins)

@theme { } in CSS; @source for content; @plugin for plugins — or keep the JS file via @config "../tailwind.config.js"

@tailwind base; @tailwind components; @tailwind utilities;

@import "tailwindcss";

PostCSS plugin: tailwindcss

@tailwindcss/postcss (or @tailwindcss/vite for Vite)

npx tailwindcss CLI

npx @tailwindcss/cli

 
/* v4 */
@import "tailwindcss";
@theme { --color-brand: #3f3cbb; }

Renamed utilities

v3 v4

shadow-sm

shadow-xs

shadow

shadow-sm

drop-shadow-sm / drop-shadow

drop-shadow-xs / drop-shadow-sm

blur-sm / blur

blur-xs / blur-sm

backdrop-blur-sm / backdrop-blur

backdrop-blur-xs / backdrop-blur-sm

rounded-sm / rounded

rounded-xs / rounded-sm

outline-none

outline-hidden

bg-gradient-to-r

bg-linear-to-r

Removed utilities and options

  • flex-shrink- / flex-grow- → shrink- / grow-

  • overflow-ellipsis → text-ellipsis

  • bg-opacity-, text-opacity-, border-opacity-, divide-opacity-, ring-opacity-, placeholder-opacity- → the / opacity modifier (bg-black/50)

  • Config keys corePlugins, safelist, separator are gone; content is replaced by @source

Changed defaults and behaviour

<!-- border / divide colour is now currentColor, not gray-200 -->
<div class="border border-gray-200"></div>

<!-- ring is now 1px + currentColor (was 3px + blue-500) -->
<button class="ring-3 ring-blue-500"></button>

<!-- the important marker moved to the end -->
<div class="bg-red-500!"></div>          <!-- v3: !bg-red-500 -->

<!-- arbitrary CSS-variable shorthand -->
<div class="bg-(--brand)"></div>          <!-- v3: bg-[--brand] -->

<!-- variant stacking now reads left-to-right -->
<ul><li class="*:first:pt-0"></li></ul>   <!-- v3: first:*:pt-0 -->

Also: hover: only applies where the device actually supports hover; space-x- / space-y- and divide-* use a faster :not(:last-child) selector; Preflight changes the placeholder colour, gives button cursor: default, and resets <dialog> margins.

Browser baseline

v4 requires Safari 16.4+, Chrome 111+, Firefox 128+ — it depends on @property and color-mix() and has no build-time fallback for older engines. A project that must support them should stay on Tailwind v3.4.

Reading the v3-era books against v4

Still applies verbatim Mentally translate

The utility-first workflow; managing duplication with components/loops; most utility names; variants (hover:, md:, dark:, group-, peer-); the mobile-first breakpoint model; arbitrary values in [ ]

tailwind.config.js → @theme; @tailwind directives → @import; theme() → var(--…); the renamed shadow/blur/rounded/outline classes; bg-opacity-* → /; JIT "engine" framing (v4 is always JIT); bg-[--x] → bg-(--x)

Related pages