Convert your Tailwind v3 config to v4 @theme CSS in seconds.
Paste your tailwind.config.js theme block. Get the equivalent Tailwind v4 @theme CSS output instantly. No Node.js, no file changes, no setup.
How TailwindConfigConverter works
- 1
Paste your config or pick an example
Paste your full tailwind.config.js, just the theme.extend object, or click one of the two example presets to see the converter in action.
- 2
The config is parsed in your browser
A lightweight parser reads the JavaScript object literal: objects, arrays, strings, and numbers. Comments and trailing commas are handled automatically. require() calls, spreads, and function values are flagged as unsupported rather than guessed at.
- 3
theme.extend is located automatically
The converter looks for module.exports / export default, then theme.extend (falling back to theme, then the root object) so you can paste a full config file or just the relevant block.
- 4
Each section maps to v4 naming conventions
colors, spacing, fontFamily, fontSize, fontWeight, letterSpacing, lineHeight, screens, borderRadius, boxShadow, and zIndex are walked recursively and converted to --color-*, --spacing-*, --font-*, and the other v4 variable prefixes.
- 5
Review the coverage report
Every section shows how many CSS variables were generated, and any values that couldn't be statically converted (dynamic expressions, plugins, keyframes) are listed so you know exactly what needs manual attention.
- 6
Copy the @theme block
Copy the generated CSS and paste it into your stylesheet inside an @theme { ... } block, right after your @import "tailwindcss" statement.
What the coverage report means
After converting, each section of your config gets one of three statuses so you know exactly what to check before committing the result.
At least one CSS variable was generated for this section. If some values inside the section couldn't be converted (a dynamic expression, a spread, a function call), they're listed individually so you can add them by hand.
colors: { primary: '#3b82f6', accent: '#f59e0b' }
# -> Converted: 2 variables generatedThe section exists in your config but every value inside it was unsupported (e.g. the whole section is require('./colors') or a spread of an external object). Nothing was generated for this section, and it needs manual conversion.
colors: require('./tailwind-colors')
# -> No values found: dynamic value, convert manuallyA top-level key that isn't part of @theme in Tailwind v4: plugins, keyframes, animation, variants, and similar configuration that lives outside the design-token system. These stay in tailwind.config.js (or move to plugin code) and aren't expected to appear in @theme.
plugins: [require('@tailwindcss/forms')]
# -> Skipped: not part of @theme, migrate manuallySupported theme.extend sections
Every section below is mapped to its Tailwind v4 CSS variable prefix. Nested objects (like color scales) are flattened with a hyphen, and a DEFAULT key drops the suffix entirely.
| theme.extend key | v4 variable prefix |
|---|---|
| colors | --color-* |
| spacing | --spacing-* |
| fontFamily | --font-* |
| fontSize | --text-* |
| fontWeight | --font-weight-* |
| letterSpacing | --tracking-* |
| lineHeight | --leading-* |
| screens | --breakpoint-* |
| borderRadius | --radius-* |
| boxShadow | --shadow-* |
| zIndex | --z-* |
The full v3 → v4 naming reference, including the DEFAULT key and font-size line-height pairs, is available as a collapsible table inside the tool above.
When to use TailwindConfigConverter
| Scenario |
|---|
| Previewing a v4 migration before touching the project |
| Migrating just your color palette |
| Converting a design system's token file |
| Understanding the v4 naming convention |
| Setting up a brand-new v4 project's theme |
| Checking what a plugin-heavy config still needs |
Frequently Asked Questions
How do I convert tailwind.config.js to Tailwind v4?
Paste the contents of your tailwind.config.js (or just the theme.extend object) into the converter above. It parses the object literal, maps each section (colors, spacing, fontFamily, and more) to the equivalent Tailwind v4 CSS variable names, and outputs a ready-to-paste @theme block.
For a full project migration, the official npx @tailwindcss/upgrade CLI handles the rest of the upgrade (imports, utility renames, etc.). This tool is for previewing and converting your custom theme values without installing anything.
What replaces tailwind.config.js in Tailwind v4?
Tailwind v4 is CSS-first. Instead of a JavaScript config file, custom theme values are defined directly in your CSS using an @theme block:
@import "tailwindcss";
@theme {
--color-primary-500: #3b82f6;
--spacing-18: 4.5rem;
--font-sans: Inter, system-ui;
}Each --variable becomes both a CSS custom property and a new utility class (e.g. --color-primary-500 generates bg-primary-500, text-primary-500, border-primary-500, and so on). tailwind.config.js still works for plugins and advanced configuration, but theme values move to CSS.
How do I define custom colors in Tailwind v4?
Add --color-<name> variables to your @theme block. For a full color scale, use --color-<name>-<shade>:
@theme {
--color-accent: #f59e0b;
--color-primary-50: #eff6ff;
--color-primary-500: #3b82f6;
--color-primary-700: #1d4ed8;
}This makes bg-accent, bg-primary-50, bg-primary-500, text-primary-700, and every other color utility variant available automatically. A v3 colors.primary.DEFAULT value maps to --color-primary (no shade suffix).
What is the @theme directive in Tailwind CSS?
@theme is a Tailwind v4 CSS at-rule used to define design tokens (colors, spacing, fonts, breakpoints, and more) as CSS custom properties. Tailwind reads these variables at build time to generate utility classes, and they're also available at runtime as regular CSS variables (var(--color-primary-500)).
It replaces the theme.extend section of tailwind.config.js for most common customizations: colors, spacing scale, font families, font sizes, breakpoints, border radius, box shadows, and more.
Why are some sections of my config not converted?
The converter handles the most common theme.extend sections: colors, spacing, fontFamily, fontSize, fontWeight, letterSpacing, lineHeight, screens, borderRadius, boxShadow, and zIndex.
Sections like plugins, keyframes, animation, and variants aren't part of @theme in v4 and are flagged as 'Skipped' in the coverage report so you know to migrate them by hand. Values that use require(), spreads, or function calls also can't be statically converted and are reported individually.
Does TailwindConfigConverter send my config to a server?
No. The entire conversion runs in JavaScript in your browser. Your config is never uploaded, and no files in your project are modified. This makes it safe to use for exploratory previews before committing to a migration.
How is this different from the official @tailwindcss/upgrade CLI?
| npx @tailwindcss/upgrade | TailwindConfigConverter | |
|---|---|---|
| Setup required | Node.js + project install | None, runs in browser |
| Modifies files | Yes, rewrites your project | No, preview only |
| Partial conversion | No, full project upgrade | Yes, paste any subset |
| Coverage report | Console output | Per-section breakdown |
Use TailwindConfigConverter to preview the conversion or migrate a design token file in isolation. Use the official CLI for a full project upgrade, including utility class renames across your codebase.