Migrate Tailwind v3 code toward v4: rename utilities per the official upgrade guide (shadow-sm→shadow-xs, ring→ring-3, outline-none→outline-hidden…) and convert theme config objects into v4 @theme CSS.
Show calculation steps
Processed privately in your browser — nothing you paste is uploaded, logged or stored.
What actually changes between v3 and v4
Tailwind v4 is a rewrite: configuration moved from JavaScript into CSS (@theme), the default palette moved to OKLCH, and a set of utilities were renamed — the size scales for shadow, blur and rounded each shifted down one step (v3’s shadow-sm is v4’s shadow-xs, bare shadow became shadow-sm), outline-none became outline-hidden, bare ring became ring-3, gradients moved from bg-gradient-to-r to bg-linear-to-r, and flex-shrink/flex-grow shortened to shrink/grow.
Two conversion modes
Classes mode applies that rename table to any markup or class list, preserving variants (hover:shadow → hover:shadow-sm) and reporting every change. Config mode takes the theme object from tailwind.config.js and emits the equivalent @theme block — colors to --color-*, borderRadius to --radius-*, fontSize to --text-*, screens to --breakpoint-*.
Worked example
v3: <button class="rounded shadow-sm ring outline-none">
v4: <button class="rounded-sm shadow-xs ring-3 outline-hidden">Honest limitations — read before shipping
- Config mode converts data, not code: plugins, presets, functions and require() are reported as out of scope, never guessed at.
- Deprecated patterns like
bg-opacity-50are flagged for manual migration to the slash syntax (bg-black/50) rather than auto-rewritten. - v4 also changes silent defaults — border/divide color is now currentColor, ring width 1px — which no textual converter can catch. Do a visual pass.
- For a full project migration, the official codemod
npx @tailwindcss/upgradeis the right tool; this converter is for understanding the mapping and migrating snippets.
How to use the Tailwind v3 to v4 Converter
- Choose the mode: utility classes in markup, or a theme config object.
- Paste your v3 classes/HTML — or the theme part of tailwind.config.js.
- Click "Convert to v4".
- Review the rename list and the manual-migration warnings before shipping.
Frequently asked questions
Which class renames does it apply?
The rename table from the official v4 upgrade guide: the shadow/blur/rounded scale shift (shadow-sm→shadow-xs, shadow→shadow-sm, same for blur and rounded), outline-none→outline-hidden, ring→ring-3, bg-gradient-to-*→bg-linear-to-*, and flex-shrink/flex-grow→shrink/grow — variants preserved.
What does config mode produce?
A v4 @theme CSS block: colors become –color-*, spacing –spacing-*, borderRadius –radius-*, fontSize –text-*, screens –breakpoint-* and so on. Sections without a direct @theme namespace are listed as skipped instead of silently dropped.
Can it convert my whole tailwind.config.js?
Only the data: plugins, presets, content globs and any JavaScript (functions, require()) are out of scope and reported honestly. For a real project migration, the official codemod — npx @tailwindcss/upgrade — is the right tool; this converter is for understanding the mapping and migrating snippets by hand.
Is renaming classes all v4 migration takes?
No — v4 also changes defaults with no textual marker, like border and divide color defaulting to currentColor and ring width becoming 1px. After renames, a visual pass over the UI is still required; the tool says so on every run.
