How to Install Tailwind CSS v4 in a WordPress Theme

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.

This guide covers Tailwind CSS v4 specifically. If you maintain a v3 theme, see the Tailwind v3 install and config guide instead.
Tailwind CSS v4.0 official release announcement

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 @theme instead of a JavaScript file.
  • No more @tailwind directives – 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 tailwindcss to @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 -v in 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.

Tailwind v4 targets modern browsers only: Safari 16.4+, Chrome 111+, and Firefox 128+. On older browsers the styles break with no graceful fallback, so check your audience’s browser stats before committing a client project to v4.

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 -v shows anything below 20, nvm install --lts is 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.

  1. Install nvm:
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash
  2. Restart your terminal, or load nvm in the current one:
    source ~/.nvm/nvm.sh
  3. Install the current LTS release of Node.js. nvm switches to it right away:
    nvm install --lts
  4. Verify the installation:
    node -v
    npm -v

    Both 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

  1. Download the LTS installer from nodejs.org.
  2. Run the installer and keep the default options.
  3. Open a new Command Prompt or PowerShell window and run node -v and npm -v to 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.

Keep this terminal open while you work. The --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 -v and upgrade if needed. If you use nvm, run nvm install --lts.
  • Styles not appearing: Make sure the --watch process is running. Check that dist/output.css exists 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 @source directive 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() with get_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:

Can I use Tailwind CSS v4 with an existing WordPress theme?
Yes. You can install Tailwind v4 in any WordPress theme you have file access to. Navigate to the theme's root directory, run the install command, create the CSS source file, and enqueue the output. One catch: your theme's existing CSS wins over Tailwind classes when both style the same element, because v4 keeps its utilities in a cascade layer. The Troubleshooting section above shows how to fix that.
Do I still need a tailwind.config.js file in v4?
No. Tailwind v4 uses CSS-first configuration. Customizations like colors, fonts, and spacing are defined directly in your CSS file using the @theme directive. There is no JavaScript config file to create or maintain.
What Node.js version does Tailwind CSS v4 require?
Tailwind CSS v4 requires Node.js version 20 or higher. You can check your version by running node -v in the terminal. If you need to upgrade, use nvm or download the latest LTS from nodejs.org.
How does automatic content detection work in v4?
Tailwind v4 automatically scans all files in your project for utility classes, excluding anything listed in your .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.
Can I upgrade my existing v3 WordPress theme to v4?
Yes. Tailwind provides an automated upgrade tool you can run with 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.
What is the difference between the CLI and PostCSS installation methods?
The CLI method uses @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.

Discussion
[  0 Comments  ]

Leave a Comment

To add code, use the buttons below. For instance, click the PHP button to insert PHP code within the shortcode. If you notice any typos, please let us know!