Adding Tailwind CSS to New and Existing WordPress Themes | CSS tricks (2023)

In the 15 or so years since I started building WordPress websites, nothing has had a bigger impact on my productivity — and my ability to enjoy front-end development — than addingTailwind CSSto my workflow (and it's not close).

When I first started working with Tailwind, there was an up-to-date first-party repository on GitHub that describes how to use Tailwind with WordPress. This repository has not been updated since 2019. But this lack of updates isn't a statement of Tailwind's usefulness for WordPress developers. By doing what Tailwind does best while WordPress still remains WordPress, Tailwind makes it possible to leverage the best parts of both platforms and build modern websites in less time.

The minimal setup example in this article aims to provide an update to this original setup repository, revised to work with the latest versions of Tailwind and WordPress. This approach can be extended to work with all types of WordPress themes, from a standard forked theme to something completely custom.

Why WordPress developers should care about Tailwind

Before we talk about setup, it's worth taking a step back and discussing how Tailwind works and what that means in a WordPress context.

Tailwind lets you style HTML elements using pre-existing helper classes, eliminating the need to write most or all of your website's CSS yourself. (Think of classes likehiddenforDisplay: hiddenorCapital letterforText transformation: uppercase.) If you've used frameworks like Bootstrap and Foundation in the past, the biggest difference you'll notice with Tailwind CSS is the undescribed design approach combined with the ease of using CSS only, with just a CSS reset included By default. These properties allow for highly optimized websites without pushing developers towards aesthetics built into the framework itself.

Also, unlike many other CSS frameworks, it is not possible to load a "default" build of Tailwind CSS from an existing CDN. With all its helper classes, the generated CSS file would just be too big. Tailwind offers a "Play CDN', but it's not intended for production as it significantly reduces Tailwind's performance benefits. (However, it comes in handy if you want to rapid prototyp or otherwise experiment with Tailwind without actually installing it or setting up a build process.)

This need to use Tailwind's build process to create a subset of the framework's utility classes specific to your project makes it important to understand how Tailwind decides which utility classes to include, and how this process affects the use of utility classes in the WordPress editor.

And finally, Tailwind is aggressivepreflight(his version of aCSS-Reset) means that some parts of WordPress with its default settings are not well suited for the framework.

Let's start by looking at where Tailwind works well with WordPress.

Where Tailwind and WordPress work well together

In order for Tailwind to work well without significant customization, it needs to act as the primary CSS for a given page. This eliminates a number of use cases within WordPress.

If you are building a WordPress plugin and need to include front-end CSS, for example, Tailwind's preflight would be in direct conflict with the active theme. If you need to style the WordPress admin panel - outside of the editor - the custom admin panel styles can also be overridden.

There are ways to work around both of these problems: you can disable preflight and add a prefix to all your utility classes, or you can use PostCSS to add a namespace to all your selectors. Either way, your configuration and workflow will become more complicated.

But when you create a theme, Tailwind is ready to go. I've had success creating custom themes with both the classic editor and the block editor, and I'm optimistic that as full website editing matures, there will be a number of full website editing features that work well alongside Tailwind .

In her blog post “Gutenberg Full Site Editing doesn't have to be full' Tammie Lister describes full page editing as a set of separate functions that can be partially or fully adopted. It's unlikely that the Global Styles full site editing functionality will ever work with Tailwind, but many other features likely will.

So you create a theme, Tailwind is installed and configured, and you add utility classes with a smile on your face. But do these utility classes work in the WordPress editor?

With planning, yes! Utility classes can be used in the editor as long as you decide in advance which ones you want to use. You cannot open the editor and use all Tailwind helper classes; Built into Tailwind's emphasis on performance is the restriction that only the utility classes used by your theme can be included. Therefore, you must tell Tailwind in advance which ones are required in the editor even though they are missing elsewhere in your code.

There are several ways to do this: You cansecurity listin your Tailwind configuration file; You can add comments with lists of classes next to the code for custom blocks that you want to style in the block editor; You could even just create a file listing all your editor-specific classes and tell Tailwind to include it as one of the source files to watch for class names.

The need to pre-commit to editor courses has never held me back from my work, but this remains the most frequently asked aspect of the Tailwind-WordPress relationship.

A minimal WordPress theme with minimal Tailwind CSS integration

Let's start with the most basic WordPress theme possible. There are only two required files:

• style.css
• index.php

We generatestyle.csswith a tailwind. Forindex.php, let's start with something simple:

<!doctype html><html lang="de"> <head> <?php wp_head(); ?> <link rel="stylesheet" href="<?php echo get_stylesheet_uri(); ?>" type="text/css" media="all" /> </head> <body> <?php if ( have_posts () ) {während (have_posts()) { the_post(); the_title( '<h1 class="entry-title">', '</h1>' ); ?> <div class="entry-content"> <?php the_content(); ?> </div> <?php } } ?> </body></html>

There are many things a WordPress theme should do that the above code doesn't do - things like pagination, post thumbnails, enqueuing style sheets instead of using themshortcutelements etc - but that's enough to show a post and test if Tailwind is working as it should.

On the Tailwind side, we need three files:

• Package.json
• tailwind.config.js
• An input file for Tailwind

Before we go any further, you will neednpm. If you are uncomfortable working with it, we have oneBeginner's Guide to npmthis is a good start!

Since there is nonePackage.jsonfile yet, let's create an empty JSON file in the same folder withindex.phpby running this command in our terminal of choice:

Echo {} > ./Paket.json

With this file we can install Tailwind:

npm install tailwindcss --save-dev

And generate our Tailwind configuration file:

npx tailwindcss init

In ourtailwind.config.jsfile, all we have to do is tell Tailwind to look for helper classes in our PHP files:

module.exports = { content: [./**/*.php"], theme: { extension: {}, }, plugins: [],}

If our theme is usedcomposer, we would want to ignoreSalespersondirectory by adding something like"!**/Salesperson/**"for theContentsRow. But if all your PHP files are part of your theme, the above will work!

We can name our input file whatever we want. Let's create a file calledTailwind.cssand add this:

/*!Designname: WordPress + Tailwind*/@tailwind base;@tailwind components;@tailwind tools;

The top comment is required by WordPress to recognize the topic; the three@tailwindDirectives add all layers of Tailwind.

And that's it! We can now run the following command:

npx tailwindcss -i ./tailwind.css -o ./style.css --watch

This tells the Tailwind CLI to generate oursstyle.cssuse fileTailwind.cssas an input file. The--regardflag will continually rebuild thestyle.cssFile can be added or removed as helper classes from any PHP file in our project repository.

It's as simple as a Tailwind-powered WordPress theme could be, but unlikely you'll ever want to use it in production. So let's talk about some avenues to a production-ready theme.

Adding TailwindCSS to an existing theme

There are two reasons you might want to add Tailwind CSS to an existing theme that already has its own vanilla CSS:

• To experiment with adding Tailwind components to an already designed theme
• How to switch a theme from vanilla CSS to Tailwind

We'll demonstrate this by installing Tailwind in Twenty Twenty-One, the default WordPress theme. (Why not Twenty Twenty-Two? The latest default WordPress theme is meant to demonstrate site-wide editing and isn't well-suited for a Tailwind integration.)

To start, you should download the theme and install it in your development environment if it is not installed there. After that, we just have to follow a few steps:

• In your terminal, navigate to the theme folder.
• Because Twenty Twenty-One already has its ownPackage.jsonFile, install Tailwind without creating a new one:

npm install tailwindcss --save-dev

• Add yourtailwind.config.jsonFile:

npx tailwindcss init

• Update yourstailwind.config.jsonFile so that it looks the same as the ones in the previous section.
• Copy the existing ones from Twenty Twenty-Onestyle.cssfile toTailwind.css.

Now we need to add our three@tailwindinstructions to theTailwind.cssFile. I suggest structuring your tailwind.css file like this:

/* WordPress theme file header goes here. */@tailwind base;/* All existing CSS goes here. */@tailwind components; @tailwind utilities;

Put theBaselayer immediately after the theme header ensures that WordPress will still recognize your theme, while also ensuring that Tailwind's CSS reset occurs as early in the file as possible.

All existing CSS follows thisBaselevel to ensure these styles take precedence over reset.

And finally thecomponentsAndUtilitiesLayers follow so they can take precedence over any CSS declarations with the same specificity.

And now, as with our minimal theme, let's run the following command:

npx tailwindcss -i ./tailwind.css -o ./style.css --watch

with your new onestyle.cssFile that is now generated every time you modify a PHP file, you should check your revised theme for minor rendering differences from the original. These are caused by Tailwind's CSS reset, which resets things a bit further than some themes might expect. In the case of Twenty Twenty-One, the only fix I made was adding itText trim line: underlinedfor theAElement.

When this rendering issue is fixed, we'll add theHeader-Banner-Componentout ofTailwind UI, Tailwind's first-party component library. Copy the code from the Tailwind UI site and paste it immediately after the "Skip to content" linkheader.php:

Pretty good! Now that we want to use helper classes to override some of the existing higher specificity classes built into the theme, let's add a single line to thetailwind.config.jsFile:

module.exports = { important: true, content: [./**/*.php"], subject: { extend: {}, }, plugins: [],}

This marks all Tailwind CSS utilities as!importantso that they can overwrite existing classes with a higher specificity. (I never hiredimportantToTRUEin production, but I would almost certainly do it if I was in the process of converting a site from vanilla CSS to Tailwind.)

With a quicknot underlinedAdded class to "More Info" link andbg-transparentAndlimit-0added to the decline button, we're done:

It looks a bit confusing when integrating the Tailwind UI components into a standard WordPress theme, but it's a great demonstration of the Tailwind components and their inherent portability.

Start from scratch

When you create a new theme with Tailwind, your process will look very similar to the minimal example above. Rather than running the Tailwind CLI directly from the command line, you'll probably want to create separate npm scripts for development and production builds and watch for changes. You may also want to create a separate build specifically for the WordPress editor.

If you're looking for a starting point that goes beyond the minimal example above - but not so far beyond that it comes with idiosyncratic styles - I've created oneTailwind optimized WordPress theme generatorinspired byunderscores(_s), once the canonical WordPress starter theme. Called _tw, this is the quickstart I wish I had when I first combined Tailwind with WordPress. It remains the first step in all my client projects.

If you're ready to go beyond the structure of a typical WordPress theme and add Laravel Blade templates to your toolkit,sageis a good choice and they have asetup guidespecifically for Tailwind to help you get started.

However you choose to start, I encourage you to take some time to get used to Tailwind CSS and styling HTML documents with helper classes: it may feel unusual at first, but you'll soon find that you can do more Take on client work than before because you're building websites faster than you used to - and hopefully, like me, have more fun doing it.