Tailwind CSS v4 is a ground-up rewrite of the framework with a completely new installation process. If you used Tailwind v3 in a WordPress theme before, forget everything you knew about tailwind.config.js and @tailwind directives – v4 replaces all of that.
This guide walks you through setting up Tailwind CSS v4 in a WordPress theme from scratch using the Tailwind CLI.
If you are bringing over a whole AI-generated app (v0, Lovable, and Bolt all output Tailwind), see my guide on how to convert an AI prototype to WordPress. If the source is a Figma design instead, that is my Figma to WordPress service.
I rewrote a theme from v3 to v4 recently, and the whole thing took about ten minutes. The process is shorter and simpler than v3, but the steps are different enough that you can’t just upgrade in place.
New to Tailwind? It is a utility-first CSS framework.
Instead of writing a stylesheet, you style elements with small single-purpose classes like p-4, bg-blue-500 or md:grid-cols-3, right in your templates. The build scans your theme files for those classes and generates a stylesheet that contains only the CSS you actually use.
What Changed in Tailwind CSS v4
A quick look at what changed between v3 and v4 that affects setup:
- No more
tailwind.config.js– Configuration is now done in CSS using@themeinstead of a JavaScript file. - No more
@tailwinddirectives – Instead of three separate directives, you write a single@import "tailwindcss";line. - Automatic content detection – Tailwind v4 finds your template files automatically. No need to specify content paths.
- New CLI package – The CLI moved from
tailwindcssto@tailwindcss/cli. - No
npx tailwindcss init– There is no initialization step because there is no config file to generate.
As of mid-2026 the current release line is v4.3, and none of the above changed: the install process below is the same one v4.0 shipped with.
The point releases mostly added utilities along the way, like text shadows and masks in v4.1, and scrollbar and zoom utilities in v4.3.
Prerequisites
Before starting, make sure you have the following:
- Node.js (version 20 or higher): Tailwind CSS v4 requires Node.js 20+. Check your version by running
node -vin the terminal. If you need to install or update Node.js, download it from the official Node.js website or follow the steps in Installing Node.js below. - A code editor: VS Code or any editor you prefer for editing theme files.
- A WordPress theme: Either an existing custom theme or a starter theme. You can use any theme that you have file access to.
Starting from scratch? Download a blank starter theme from underscores.me and install it on a local WordPress site.
Then delete the theme’s package.json. It belongs to underscores’ old Sass build, and its node-sass dependency fails to install on current Node versions, which breaks Step 1.
Other themes ship a package.json too (Twenty Twenty-Five does), and Step 1 installs whatever is listed there along with Tailwind.
Don’t add Tailwind to a theme you didn’t build, such as Twenty Twenty-Five: the next theme update replaces your files. Use a child theme instead.
One more requirement is easy to overlook: the browsers your visitors actually use.
Installing Node.js
Skip this part if node -v already prints v22 or higher. v20 still runs Tailwind v4, but it no longer gets security updates.
I hit this on a Mac that still had Node 18 from Homebrew. If
node -vshows anything below 20,nvm install --ltsis the fastest fix.
macOS and Linux (including Ubuntu)
The easiest way is nvm (Node Version Manager), which also lets you switch between Node versions per project.
- Install nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash - Restart your terminal, or load nvm in the current one:
source ~/.nvm/nvm.sh - Install the current LTS release of Node.js. nvm switches to it right away:
nvm install --lts - Verify the installation:
node -v npm -vBoth commands should print a version number.
On Ubuntu, avoid sudo apt install nodejs for this. Ubuntu 24.04 ships Node 18 in its default repositories, which is too old for Tailwind v4. nvm installs a current version without touching the system package.
Windows
- Download the LTS installer from nodejs.org.
- Run the installer and keep the default options.
- Open a new Command Prompt or PowerShell window and run
node -vandnpm -vto verify.
If node is not recognized on Windows, close the terminal and open a new one: the PATH change only applies to windows opened after the install.
On macOS and Linux, if nvm is not found, check that the installer added its loading lines to your ~/.zshrc or ~/.bashrc.
Step 1 – Install Tailwind CSS v4
Open your terminal, navigate to the root directory of your WordPress theme, and run:
npm install tailwindcss @tailwindcss/cli
Two packages: the core library and the CLI that runs the build. That’s it. No init, no config file.
After the installation completes, you should see a node_modules folder and a package.json file in your theme directory.
Step 2 – Create the Input CSS File
Create a folder named src in the root directory of your theme. Inside it, create a file named input.css with a single line:
@import "tailwindcss";
That single line replaces the three @tailwind directives that v3 required (@tailwind base, @tailwind components, @tailwind utilities). Tailwind v4 handles all of that with one import.
Step 3 – Run the Build Process
Run the following command from your theme’s root directory:
npx @tailwindcss/cli -i ./src/input.css -o ./dist/output.css --watch
This command tells Tailwind to read your src/input.css, scan your theme files for utility classes, and output the compiled CSS to dist/output.css. The --watch flag keeps the process running so it recompiles automatically whenever you make changes.
--watch process must be running for Tailwind to detect new classes and regenerate the CSS.What About Content Paths?
In v3, you had to manually specify which files Tailwind should scan in tailwind.config.js. In v4, Tailwind automatically detects your template files. It respects your .gitignore file and skips binary files, so it won’t scan node_modules or images.
If you ever need to include a source that Tailwind doesn’t pick up automatically, such as templates in a plugin, add it with the @source directive in your CSS.
The path is relative to the CSS file, so from wp-content/themes/your-theme/src/input.css a plugin folder is three levels up:
@import "tailwindcss";
@source "../../../plugins/my-plugin/templates";
The opposite also works. To stop Tailwind from scanning a folder, such as old templates you no longer load, use @source not (Tailwind v4.1 and later):
@source not "../template-parts/legacy";
Step 4 – Enqueue the CSS in WordPress
Next, load the compiled CSS in your theme. Open your theme’s functions.php and add:
function theme_tailwind_styles() {
wp_enqueue_style(
'tailwind',
get_template_directory_uri() . '/dist/output.css',
array(),
filemtime( get_template_directory() . '/dist/output.css' )
);
}
add_action( 'wp_enqueue_scripts', 'theme_tailwind_styles' );
Using filemtime() as the version parameter ensures the browser cache is busted every time the CSS file changes. This way, you won’t have to clear the cache manually during development.
If the enqueue pattern is new to you, the guide on how to properly enqueue CSS and JavaScript in WordPress covers it in depth.
Step 5 – Start Using Tailwind
Open any template file in your theme (e.g. header.php, index.php, or a template part) and add a Tailwind class to test it.
In a block theme there are no PHP templates: put the markup in a Custom HTML block inside parts/header.html or one of the files in templates/. For example:
<div class="bg-blue-500 text-white p-8 text-center">
<h1 class="text-3xl font-bold">Tailwind v4 is working!</h1>
</div>
Make sure the --watch process is still running in your terminal, then refresh the page. You should see a blue box with white text.
Example: Responsive Card Grid
A more realistic example – a responsive card grid that stacks on mobile and shows three columns on medium screens:
<div class="mx-auto max-w-5xl p-6">
<div class="grid grid-cols-1 gap-6 md:grid-cols-3">
<div class="rounded-lg bg-white p-6 shadow-lg">
<h2 class="mb-2 text-xl font-bold">Card One</h2>
<p class="text-gray-600">Content for the first card goes here.</p>
</div>
<div class="rounded-lg bg-white p-6 shadow-lg">
<h2 class="mb-2 text-xl font-bold">Card Two</h2>
<p class="text-gray-600">Content for the second card goes here.</p>
</div>
<div class="rounded-lg bg-white p-6 shadow-lg">
<h2 class="mb-2 text-xl font-bold">Card Three</h2>
<p class="text-gray-600">Content for the third card goes here.</p>
</div>
</div>
</div>
Example: Centered Hero Section
And a centered hero section with a heading, a short description and a button:
<div class="bg-blue-500 py-20 text-white">
<div class="container mx-auto px-4 text-center">
<h1 class="mb-4 text-4xl font-bold">Welcome to Tailwind CSS</h1>
<p class="mb-8 text-lg">Tailwind CSS is a utility-first CSS framework for rapid UI development.</p>
<a href="#" class="rounded-md bg-white px-4 py-2 font-semibold text-blue-500">Get Started</a>
</div>
</div>
Customizing Your Theme with CSS
In v3, you customized colors, fonts, and spacing in tailwind.config.js. In v4, you do it directly in your CSS file using the @theme directive:
@import "tailwindcss";
@theme {
--color-brand: #a3316f;
--color-brand-dark: #8a2a5e;
--font-heading: "Inter", sans-serif;
--font-body: "IBM Plex Sans", sans-serif;
--breakpoint-3xl: 120rem;
--radius-card: 1.25rem;
}
After adding these, you can use them as utility classes: bg-brand, text-brand-dark, font-heading, font-body, 3xl:grid-cols-4 and rounded-card. All theme variables are also exposed as native CSS custom properties, so you can reference them anywhere with var(--color-brand).
Note that @theme only names the fonts. You still have to load them, either by enqueuing the font CSS or by self-hosting the files.
Spacing needs no config at all. v4 derives every spacing utility from one variable, --spacing (0.25rem by default), so values outside the old scale such as p-13 or mt-17 work out of the box.
Classes Built in PHP or ACF
Tailwind finds classes by reading your files as plain text. It never runs PHP, so a class name assembled at runtime never reaches the CSS:
<?php $color = get_field( 'accent_color' ); // "red", "green" or "blue" ?>
<p class="text-<?php echo esc_attr( $color ); ?>-600">Accent text</p>
Tailwind never sees text-red-600 in that file, so the class doesn’t exist in the output. The cleanest fix is to keep the complete class names in the file, where the scanner can find them:
<?php
$accent_classes = array(
'red' => 'bg-red-100 text-red-800',
'green' => 'bg-green-100 text-green-800',
'blue' => 'bg-blue-100 text-blue-800',
);
$color = get_field( 'accent_color' );
$class = $accent_classes[ $color ] ?? 'bg-gray-100 text-gray-800';
?>
<p class="<?php echo esc_attr( $class ); ?>">Accent text</p>
When the class names can’t live in a PHP file, for example when editors type them into a field or into the block editor’s “Additional CSS class(es)” box, safelist them in your CSS with @source inline() (Tailwind v4.1 and later). Braces expand, so one line covers every combination:
@source inline("text-{red,green,blue}-700");
Custom Utilities
Use @utility for your own classes. Unlike a plain CSS class, a utility registered this way works with variants, so you get hover: and md: versions for free:
@utility content-auto {
content-visibility: auto;
}
You can now write content-auto or md:content-auto in your templates.
Plugins
Plugins load with @plugin. The one most WordPress themes need is the official typography plugin.
Its prose class styles the HTML that the_content() outputs (headings, lists, quotes, tables) without a class on every element. Install it:
npm install @tailwindcss/typography
Load it in your CSS:
@plugin "@tailwindcss/typography";
And wrap the post content in your template:
<article class="prose lg:prose-xl">
<?php the_content(); ?>
</article>
Class-Based Dark Mode
By default, dark: utilities follow the visitor’s operating system setting (prefers-color-scheme). If your theme has a toggle that adds a dark class to the <html> element, redefine the variant:
@custom-variant dark (&:where(.dark, .dark *));
Now dark:bg-gray-900 applies only when the dark class is present.
Splitting the Config into Files
As the theme grows, move the @theme block into its own file and import it after Tailwind:
/* src/input.css */
@import "tailwindcss";
@import "./theme.css";
The theme.css file then contains only the @theme { ... } block, and you can add more files the same way for utilities or plugin settings.
Adding a Build Script to package.json
Instead of typing the full CLI command every time, add a build script to your package.json:
{
"scripts": {
"dev": "npx @tailwindcss/cli -i ./src/input.css -o ./dist/output.css --watch",
"build": "npx @tailwindcss/cli -i ./src/input.css -o ./dist/output.css --minify"
}
}
If your package.json already has a build script (Twenty Twenty-Five ships one for its own CSS), give yours another name, such as build:css, so you don’t overwrite it.
Now you can run npm run dev during development and npm run build for a minified production build before deploying.
When you deploy, the server only needs the theme files and dist/output.css. Leave node_modules out of the upload: in my test theme it weighed about 19 MB.
Troubleshooting
Common issues you might run into:
- Node.js version error: Tailwind v4 requires Node.js 20+. Run
node -vand upgrade if needed. If you use nvm, runnvm install --lts. - Styles not appearing: Make sure the
--watchprocess is running. Check thatdist/output.cssexists and is being loaded in the browser (inspect the page source). - Classes not detected: Tailwind v4 uses automatic content detection based on your
.gitignore. If your templates are in a non-standard location, use the@sourcedirective in your CSS to include them. - Classes generated but not applied: Your theme’s existing CSS is overriding them. See the explanation below this list.
- Using a child theme: If your theme is a child theme, replace
get_template_directory_uri()withget_stylesheet_directory_uri()in the enqueue function so it points to the child theme’s directory.
Why theme CSS wins. Tailwind v4 puts its utilities in a CSS cascade layer, and any unlayered CSS, such as your theme’s existing style.css, beats them regardless of specificity. In my test with underscores, its h1 { font-size: 2em; } overrode text-3xl.
In a classic theme, either stop enqueuing the old stylesheet, or move its rules into a file you import below the utilities:
@import "tailwindcss";
@import "./legacy.css" layer(base);
Keep the header comment in style.css: WordPress reads the theme name from it.
Block themes are hit harder. On Twenty Twenty-Five, the global styles WordPress prints from theme.json overrode both text-3xl and font-bold, and you can’t move those into a layer.
Mark the utilities as important instead, either per class with a trailing ! (text-3xl!) or for all of them at once:
@import "tailwindcss" important;
FAQs
Common questions about Tailwind CSS v4 in WordPress:
tailwind.config.js file in v4?
@theme directive. There is no JavaScript config file to create or maintain.
node -v in the terminal. If you need to upgrade, use nvm or download the latest LTS from nodejs.org.
.gitignore and binary file types like images. If you need to include files from outside the default scope, use the @source directive in your CSS file.
npx @tailwindcss/upgrade. It handles most of the migration automatically, including converting your config file and updating directives. For WordPress themes, you may still need to manually update the enqueue function and CLI command.
@tailwindcss/cli to compile your CSS directly from the terminal. The PostCSS method uses @tailwindcss/postcss as a PostCSS plugin, which is better suited for projects that already have a PostCSS pipeline. For most WordPress themes, the CLI method is simpler and recommended.
Summary
The whole setup is four steps and takes a few minutes. Compared to v3, the biggest relief is not having to think about content paths or maintain a separate config file.
If you want to go deeper into customizing your theme, the official Tailwind CSS v4 documentation covers everything.
For the same setup running in production, see the 7is case study: a Hebrew and English WordPress theme built on Tailwind v4, where two legacy stylesheets were replaced by a single 68.1 KB tailwind.css with no separate RTL build.
On the GN Law rebuild the same approach put one 24 KB stylesheet in front of an entire Hebrew site, replacing nine files totalling 203 KB.