Adding TailwindCSS to your WordPress theme
For the redesign of my new website, I’ve finally decided to jump on the Tailwind CSS hype train. I know, I know, I’m pretty late to the party but that’s okay, I tend to be.
The biggest hurdle for me to make the switch was the many unknowns that came with integrating it into my process of building custom WordPress themes. Even more so after the addition of the block editor.
But now I’ve finally found a way to combine those two and get the best of both worlds.
What is TailwindCSS and why should you care?
In the ~10 years I’ve been building WordPress websites, I’ve tried several different CSS frameworks. Starting with Bootstrap and Foundation, transitioning to Bulma, and finally CodyFrame.
While each of them had its fair share of advantages, none of them had such a huge impact (not even close) on my development workflow as Tailwind CSS.
Tailwind is a CSS framework designed to help you speed up the design process for your websites. Its utility-first approach allows you to apply classes like flex, w-full, text-center and shadow directly to your HTML elements (including hover, focus and other states), removing the need to write your website’s CSS yourself.
However, there are cases, when a utility class won’t do and a more “traditional” approach to CSS might be necessary. To give you an example, WordPress has a number of functions that generate their own HTML elements. While you could technically add a filter to replace the applied classes, it might be faster (and simpler) to write your own CSS.
Flexible as it is, Tailwind offers a solution for that scenario as well.
Setting up Tailwind in your local environment
Make sure you take a look at the official documentation for installing Tailwind. There are a few extra steps needed for properly setting up Tailwind in your WordPress theme. Let’s have a look!
Pre-Requisites
We’re going to use npm for setting up Tailwind CSS in our WordPress theme. If you haven’t heard of it or don’t know how to use it, I recommend checking out this guide before you proceed. With that out of the way, let’s dive right in!
Installing Tailwind CSS via npm
Navigate to the theme folder in your terminal. Make sure there’s a package.json file or create an empty one by running the following command:
echo {} > ./package.json
Next you’re going to download and install Tailwind CSS in your theme:
npm install -D tailwindcss
npx tailwindcss init
The above command should have created a tailwind.config.js file, in which you need to tell Tailwind where to look for utility classes in your theme’s files:
module.exports = {
content: ["./**/*.{php,js}"],
theme: {
extend: {},
},
plugins: [],
}
This step is important because Tailwind is only going to generate the CSS you’re actually using in your project. Tailwind focuses on performance, trying to produce the smallest CSS file possible.
For simplicity’s sake I’ve added ./**/*.{php,js} to look for utility classes in every PHP or JavaScript file in my theme folder. But you can of course define more paths if necessary.
Lastly, you need to create an input.css file for Tailwind, containing the three @tailwind directives.
@tailwind base;
@tailwind components;
@tailwind utilities;
In case you want to add it to your existing theme, I’d suggest copying your style.css to input.css and including the three Tailwind directives as follows. I’m using the main stylesheet of the Twenty Twenty theme as an example.
/*
Theme Name: Twenty Twenty
Theme URI: https://wordpress.org/themes/twentytwenty/
Author: the WordPress team
Author URI: https://wordpress.org/
Description: Our default theme for 2020 is designed to [...]
Version: 1.3
Requires at least: 5.0
Tested up to: 5.4
Requires PHP: 7.0
License: GNU General Public License v2 or later
License URI: <http://www.gnu.org/licenses/gpl-2.0.html>
Text Domain: twentytwenty
[...]
*/
@tailwind base;
/* Your existing CSS */
@tailwind components;
@tailwind utilities;
Now you can finally run the command to start Tailwind CLI’s build process. Make sure to match the paths to your theme folder:
npx tailwindcss -i ./assets/css/input.css -o ./assets/css/output.css --watch
Your input.css is now being watched. Every time you change one of the files included in the paths you defined earlier in your tailwind.config.js file, your output.css should be re-generated.
One more note on using Tailwind to upgrade the CSS of an existing theme: It might come in handy to override some of the classes used in your theme. You can do so by simply adding the following line to your tailwind.config.js file:
module.exports = {
important: true,
content: ["./**/*.{php,js}"],
theme: {
extend: {},
},
plugins: [],
}
Now all Tailwind utility-classes should be marked as !important, overriding existing classes. I would highly advise against using it in production. You can remove the line as soon as you’re done converting your theme to Tailwind CSS.
Integrating Tailwind CSS into your WordPress theme
Before any of the new styles show up in the browser, you need to enqueue Tailwind in the functions.php of your theme. Here’s an example from my own theme (again, make sure to match the paths to your theme folder):
/**
* Enqueue theme assets
*/
function ag_theme_scripts() {
// Enqueue the main stylesheet
wp_enqueue_style( 'main', get_template_directory_uri() . '/style.css' );
// Enqueue the tailwind stylesheet
wp_enqueue_style( 'tailwind', get_template_directory_uri() . '/assets/css/output.css' );
}
add_action( 'wp_enqueue_scripts', 'ag_theme_scripts' );
Using Tailwind CSS with Gutenberg block editor
If you’re using the Gutenberg block editor and want it to look like on the front end, you have to enqueue Tailwind CSS there as well.
/**
* Enqueue Gutenberg assets
*/
function ag_gutenberg_scripts() {
wp_enqueue_style( 'tailwind', get_template_directory_uri() . '/assets/css/output.css' );
}
add_action('enqueue_block_editor_assets', 'ag_gutenberg_scripts');
Wrapping it up
And that’s it! You should now be able to use Tailwind CSS in your WordPress theme, including the Gutenberg block editor.
Tailwind also offers some plugins you might want to add to your theme. I highly recommend checking out the Typography plugin. It provides default styles, making your blog posts look great out of the box. Or any other part of your theme where you have a lot of written content.
Also, check out https://tailpress.io/ or https://underscoretw.com/ if you don’t want to start from scratch and quickly generate a new WordPress theme built with Tailwind.