Skip to content

Tailwind v3 vs v4

When to Use

Every new project decision about which Tailwind version to target. Existing v3 projects considering upgrade.

Decision

If you need... Use... Why
New project, modern browser support v4 CSS-first config, built-in container queries, 180x faster incremental builds, native CSS features
Legacy browser support (Safari <16.4) v3 v4 requires @property, color-mix() — unavailable in older browsers
Existing v3 project, stable team Stay on v3 Upgrade effort rarely pays off mid-project; plan for v4 on next major version
Shared design system across monorepo v4 CSS @theme blocks are portable, importable; v3 configs require JS module sharing
Using Vite/Next.js/SvelteKit v4 First-party framework plugins eliminate PostCSS complexity
Needing container queries today v4 Built-in; v3 requires @tailwindcss/container-queries plugin

Pattern

/* v4: single import, CSS-first config */
@import "tailwindcss";

@theme {
  --color-brand: oklch(0.65 0.18 260);
  --font-display: "Inter", sans-serif;
}

// v3: JS config file (tailwind.config.js)
module.exports = {
  content: ['./src/**/*.{html,js,ts,jsx,tsx}'],
  theme: {
    extend: {
      colors: { brand: '#4f46e5' },
      fontFamily: { display: ['Inter', 'sans-serif'] },
    },
  },
};

v3 → v4 Key Changes at a Glance

Aspect v3 v4
Config tailwind.config.js @theme {} in CSS
Import @tailwind base/components/utilities @import "tailwindcss"
Content scanning Manual content: [] paths Automatic (respects .gitignore)
PostCSS plugin tailwindcss @tailwindcss/postcss
Container queries Plugin required Built-in
Colors sRGB hex oklch (wider P3 gamut)
!important modifier !flex (prefix) flex! (suffix)
CSS variables in arbitrary bg-[--color] bg-(--color)
Browser minimum IE11+ (configurable) Safari 16.4, Chrome 111, Firefox 128
Custom utilities @layer utilities {} @utility name {}
Upgrade path — npx @tailwindcss/upgrade

Common Mistakes

  • Starting v4 without checking browser requirements — Safari 16.4+ requirement rules out some enterprise environments
  • Running the v4 upgrade tool on v3 code and committing without reviewing the diff — automated, but audit each renamed utility (shadow-sm → shadow-xs, etc.)
  • Mixing v3 @tailwind directives with v4's @import "tailwindcss" — pick one; they are not interchangeable

See Also

  • Installation & Integration
  • Reference: https://tailwindcss.com/blog/tailwindcss-v4
  • Reference: https://tailwindcss.com/docs/upgrade-guide