Tailwind CSS Tutorial · Tailwind in Real Projects · Lesson 25 of 27
Upgrading from Tailwind v3 to v4
What changed in Tailwind CSS v4, the renamed and removed classes, the new CSS-first setup, and how to upgrade a project safely.
The upgrade tool
Run the official tool in a clean Git branch; it updates dependencies, your CSS and most class names:
npx @tailwindcss/upgrade
v4 targets modern browsers (Safari 16.4+, Chrome 111+, Firefox 128+). Stay on v3.4 if you must support older ones.
Setup changes
| v3 | v4 |
|---|---|
@tailwind base; @tailwind components; @tailwind utilities; |
@import "tailwindcss"; |
tailwind.config.js with content: [...] |
automatic detection; customize with @theme in CSS |
tailwindcss PostCSS plugin |
@tailwindcss/postcss or @tailwindcss/vite |
darkMode: "class" |
@custom-variant dark (&:where(.dark, .dark *)); |
Renamed and removed classes
| v3 | v4 |
|---|---|
shadow-sm / shadow |
shadow-xs / shadow-sm |
rounded-sm / rounded |
rounded-xs / rounded-sm |
blur-sm / blur |
blur-xs / blur-sm |
outline-none |
outline-hidden (outline-none now really sets outline-style: none) |
ring (3px) |
ring-3 (ring is now 1px) |
bg-opacity-50, text-opacity-50 |
bg-black/50, text-black/50 |
flex-shrink-0, flex-grow |
shrink-0, grow |
bg-gradient-to-r |
bg-linear-to-r (the old name still works) |
Default border colour changed to currentColor (v3 used gray-200), so add a colour wherever you use border.
<div class="grid gap-4 p-6 sm:grid-cols-2">
<div class="rounded-sm border border-gray-200 p-4 shadow-xs">v4: shadow-xs, rounded-sm<br><span class="text-sm text-gray-500">(was shadow-sm, rounded)</span></div>
<div class="rounded-lg bg-black/50 p-4 text-white">bg-black/50<br><span class="text-sm text-white/70">(was bg-black bg-opacity-50)</span></div>
<button class="rounded-lg border border-gray-300 px-4 py-2 focus:ring-3 focus:ring-sky-300 focus:outline-hidden">ring-3 on focus (was ring)</button>
<div class="rounded-lg bg-linear-to-r from-fuchsia-500 to-cyan-500 p-4 text-white">bg-linear-to-r</div>
</div>
Test yourself
In v4, what replaces bg-opacity-50 on a black background?
bg-black/50bg-black-50opacity-50 bg-blackbg-black bg-alpha-50
Show answer
Answer: bg-black/50
Opacity utilities were removed in favour of the slash modifier.