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. 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.

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.

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 use nvm install --lts if you have nvm installed.
• 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.

I hit this on a Mac that still had Node 18 from Homebrew. If node -v shows anything below 20, nvm install 20 && nvm use 20 is the fastest fix.

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.

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, add it with the @source directive in your CSS:

@import "tailwindcss";

@source "../plugins/my-plugin/templates";

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. 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>

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;
}

After adding these, you can use them as utility classes: bg-brand, text-brand-dark, font-heading, font-body. All theme variables are also exposed as native CSS custom properties, so you can reference them anywhere with var(--color-brand).

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"
    }
}

Now you can run npm run dev during development and npm run build for a minified production build before deploying.

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 20 and nvm use 20.
• 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.
• 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.

Frequently Asked Questions

Common questions about Tailwind CSS v4 in WordPress:

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.