Tailwind v4 migration

Convert your Tailwind v3 config to v4

Paste your tailwind.config.js and get the CSS-first v4 version: an @theme block with your colors, fonts, spacing and breakpoints.

tailwind.config.js

v4 CSS

@import "tailwindcss";

@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";

@custom-variant dark (&:where(.dark, .dark *));

@theme {
  --color-brand: #038770;
  --color-brand-light: #27a581;
  --color-brand-dark: #026654;
  --color-accent-50: var(--color-amber-50);
  --color-accent-100: var(--color-amber-100);
  --color-accent-200: var(--color-amber-200);
  --color-accent-300: var(--color-amber-300);
  --color-accent-400: var(--color-amber-400);
  --color-accent-500: var(--color-amber-500);
  --color-accent-600: var(--color-amber-600);
  --color-accent-700: var(--color-amber-700);
  --color-accent-800: var(--color-amber-800);
  --color-accent-900: var(--color-amber-900);
  --color-accent-950: var(--color-amber-950);
  --color-surface: rgb(var(--surface));
  --font-sans: Inter, ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
  --font-display: "Cal Sans", Inter, sans-serif;
  --text-2xs: 0.625rem;
  --text-2xs--line-height: 0.875rem;
  --breakpoint-3xl: 1920px;
  --spacing-18: 4.5rem;
  --spacing-4_5: 1.125rem;
  --radius-4xl: 2rem;
  --shadow-soft: 0 2px 12px -4px rgb(0 0 0 / 0.12);
  --animate-fade-in: fade-in 200ms ease-out;

  @keyframes fade-in {
    from { opacity: 0; transform: translateY(4px); }
    to { opacity: 1; transform: translateY(0); }
  }
}

@utility container {
  margin-inline: auto;
  padding-inline: 1.5rem;
}
  • @tailwindcss/aspect-ratio is built into v4, so it's no longer needed.
  • v4 finds your source files on its own, so content is gone.
  • theme.zIndex isn't needed in v4: its utilities take any number, like z-60.
  • v4 handles opacity itself, so <alpha-value> was removed from color values. Opacity modifiers like bg-brand/50 still work.
  • Free, no sign-up
  • Runs in your browser
  • Your code never leaves your device

How to use it

How to use the Tailwind v3 to v4 Converter tool

Free, with no sign-up. Everything happens in your browser.

  1. 01

    Paste your config

    The whole tailwind.config.js, .cjs, .mjs or .ts file, imports included. It's read as text and never run.

  2. 02

    Check the notes

    The CSS updates as you type. The notes list anything v4 handles differently and anything that needs a manual change, like inline plugins.

  3. 03

    Replace your old setup

    Save the CSS as your main stylesheet in place of the @tailwind directives, install @tailwindcss/vite or @tailwindcss/postcss, and delete the config file.

Guide

What changes from Tailwind v3 to v4

Tailwind v4 moves configuration from JavaScript into CSS. Your theme becomes CSS variables in an @theme block, and the rest of the config becomes a handful of directives. Here's how each part of a v3 config maps across.

The theme becomes CSS variables

Every value in theme.extend becomes a variable in @theme, named by its namespace: colors become --color-*, fontFamily becomes --font-*, fontSize becomes --text-*, screens become --breakpoint-*, borderRadius becomes --radius-* and boxShadow becomes --shadow-*. The utilities stay the same: --color-brand still gives you bg-brand and text-brand.

Nested colors are flattened with dashes and DEFAULT becomes the bare name. Because they're real CSS variables, you can also use them anywhere in your own CSS, like var(--color-brand).

tailwind.config.js
theme: {
  extend: {
    colors: {
      brand: { DEFAULT: "#038770", dark: "#026654" },
    },
    screens: { "3xl": "1920px" },
  },
}
app.css
@import "tailwindcss";

@theme {
  --color-brand: #038770;
  --color-brand-dark: #026654;
  --breakpoint-3xl: 1920px;
}

Extending versus replacing

In v3, keys under theme.extend add to the defaults, while keys directly under theme replace them. In v4 everything in @theme adds to the defaults. To replace a whole namespace, the converter first resets it with --color-*: initial; and then adds your values, so the result matches what your v3 config did.

Some theme keys aren't needed anymore. v4 accepts any number for z-index, opacity, durations, grid columns and more, so z-60 and opacity-15 work without configuration.

Dark mode, plugins and content

darkMode: "class" becomes a custom variant: @custom-variant dark (&:where(.dark, .dark *)). Media-query dark mode is the v4 default and needs nothing.

Plugins are loaded with @plugin "@tailwindcss/typography". Container queries, aspect-ratio and line-clamp are built into v4, so those plugins can go. The content array is gone too: v4 finds your source files automatically, and @source adds any it misses, such as a UI library in node_modules.

v3
darkMode: "class",
plugins: [require("@tailwindcss/typography")],
v4
@plugin "@tailwindcss/typography";

@custom-variant dark (&:where(.dark, .dark *));

Keyframes, animations and the container

Animations become --animate-* variables, with their @keyframes written inside the @theme block, next to the animation that uses them.

The container options center and padding no longer exist. The converter writes an @utility container block with margin-inline: auto and padding-inline instead, which is the v4 way to customize it.

Renamed utilities to update in your markup

A config converter can't see your templates, so check these renamed classes when you upgrade: shadow-sm is now shadow-xs and shadow is shadow-sm, and the same shift applies to drop-shadow, blur, backdrop-blur and rounded. outline-none is now outline-hidden, and ring now means a 1px ring (use ring-3 for the old 3px).

Opacity utilities like bg-opacity-50 are gone in favor of modifiers like bg-black/50, and flex-shrink-0 and flex-grow are now shrink-0 and grow. The default border color is now currentColor, so add a color to bare border classes.

What it handles

Built for real-world code

The details that usually need fixing by hand, done for you.

  • Reads your config without running it

    The file is parsed as text, so no code from it runs in your browser. Functions and computed values are listed in the notes instead.

  • Imports resolved

    References to tailwindcss/colors, defaultTheme font stacks and constants defined in the same file are resolved to values or v4 variables.

  • The whole config, not just the theme

    prefix, important, darkMode, plugins, content, safelist and container options are converted too, each to its v4 directive.

  • Private by design

    The conversion runs in your browser. Your config isn't uploaded, stored or logged anywhere.

Import Code

Want the markup upgraded too?

Import your existing HTML and ask AI to update its Tailwind classes, then preview every version before you download the result.

FAQ

Questions about Tailwind v3 to v4 Converter

Something else on your mind? Send us a message.

Yes. It's free with no sign-up and no limits, and it runs entirely in your browser.

More free tools

Keep going

More converters for HTML, React and Tailwind.