Tailwind CSS is a powerful utility-first framework, but its real magic begins when you customize the configuration to match your project’s unique needs.
In WordPress themes, the tailwind.config.js file becomes the central place to define your design system, from colors and fonts to responsive breakpoints and advanced utilities.
Whether you’re building a client site or a starter theme, tailoring this configuration gives you full creative control.
Tailwind is not just a utility framework. It’s a full design system you control. Tweaking the
tailwind.config.jsfile gives you that power.
Basic Tailwind Configuration in WordPress
After running npx tailwindcss init, a new file called tailwind.config.js is created in the theme directory. This is where we define our custom settings and tell Tailwind where to look for class names.
For example, if your theme uses header.php in the root and templates inside template-parts, your config would look like this:
// tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
content: ["./template-parts/*.{php,html,js}","./*.{php,html,js}"],
theme: {
extend: {},
},
plugins: [],
}Tailwind scans all PHP, JS, and HTML files you specify, extracts the class names, and generates a CSS file based only on what’s in use. If a file isn’t listed, Tailwind will not include its classes.
Adding Custom Colors
To match your brand or design system, you can define a custom color palette inside the config. These values will be available through utility classes like bg-primary and text-accent.
theme: {
extend: {
colors: {
primary: '#1e40af',
secondary: '#64748b',
accent: '#f59e0b',
},
},
}Once you’ve defined your custom colors, you can use them just like any other Tailwind color utility class in your theme’s PHP files, block templates, or components. For example, to give a div a background color of primary and set the text color to accent, you can write:
<div class="bg-primary text-accent p-4 rounded">
<h2 class="text-white text-xl font-bold">Welcome</h2>
<p class="text-secondary">This section uses custom colors from your Tailwind config.</p>
</div>These utility classes now point to the exact hex values you set in the tailwind.config.js file. This approach ensures consistency across your entire design and allows you to update a color in one place instead of searching through multiple template files.
Custom Fonts
If you’re using Google Fonts or local fonts in your theme, you can register them here to make them available via Tailwind classes.
fontFamily: {
sans: ['"Inter"', 'sans-serif'],
serif: ['"Merriweather"', 'serif'],
}Then simply use font-sans or font-serif in your template files.
Spacing, Sizing, and Breakpoints
Tailwind gives you a default spacing scale, but you can expand it to include larger or more specific values as needed. This is useful for hero sections, containers, or layouts that need more room.
spacing: {
'128': '32rem',
'144': '36rem',
},
screens: {
'xs': '480px',
'3xl': '1920px',
}After defining custom spacing and breakpoints, you can use them with Tailwind’s utility classes as usual. For example, mt-128 will apply a margin-top of 32rem, and max-w-3xl will use your custom 1920px screen size in responsive designs. This lets you create layouts with more flexibility and precise control.
Custom Z-Index and Border Radius
For complex layouts and design tweaks, you may want to add custom z-index levels or larger border-radius values. These can be extended in the config like this:
zIndex: {
'60': '60',
'70': '70',
},
borderRadius: {
'4xl': '2.5rem',
},Safelist Classes for ACF or PHP
If you’re using Advanced Custom Fields or PHP to output class names dynamically, Tailwind might not detect them during the build. To prevent styles from being purged, use the safelist option:
safelist: [
'bg-blue-500',
'text-center',
/^text-(red|green|blue)-(100|200|300)$/,
]Optimize Paths for Full Theme Coverage
Tailwind only generates styles based on the files listed in your content array. For WordPress, this should include all templates, partials, and dynamic JS-rendered content.
content: [
"./*.php",
"./template-parts/**/*.php",
"./inc/**/*.php",
"./blocks/**/*.php",
"./js/**/*.js"
]Create Custom Utilities with Plugins
Tailwind allows you to write plugins to add your own custom utility classes. This is helpful when you need something not covered by the default configuration.
plugins: [
function ({ addUtilities }) {
addUtilities({
'.text-shadow': {
textShadow: '2px 2px #000',
},
'.rotate-y-180': {
transform: 'rotateY(180deg)',
},
});
},
]Watch for Changes and Build the Output CSS
After customizing your configuration, you need to compile your CSS with Tailwind’s CLI. If you haven’t done so already, create a folder named src in your theme root and inside it, add a file called input.css with the following content:
@tailwind base;
@tailwind components;
@tailwind utilities;Then run the following command in your terminal to generate the final stylesheet:
npx tailwindcss -i ./src/input.css -o ./dist/output.css --watchThis command tells Tailwind to take your source file, process all used classes from the files listed in content, and output a CSS file into the dist folder. The --watch flag ensures Tailwind keeps compiling on file changes while you work.
Finally, enqueue the generated CSS in your theme’s functions.php:
function sv_theme_scripts() {
wp_enqueue_style( 'output', get_template_directory_uri() . '/dist/output.css', array(), null );
}
add_action( 'wp_enqueue_scripts', 'sv_theme_scripts' );Split Configuration Files
If you’re working on a large project or team, it’s a good idea to split the config into separate files. This keeps everything modular and easier to maintain.
// tailwind.config.js
const colors = require('./tailwind/colors');
const spacing = require('./tailwind/spacing');
module.exports = {
theme: {
extend: {
colors,
spacing,
},
},
}Use Tailwind with PostCSS Plugins
Tailwind works seamlessly with PostCSS, allowing you to add useful plugins like nesting, autoprefixer, and more. Here’s a basic example:
// postcss.config.js
module.exports = {
plugins: {
tailwindcss: {},
autoprefixer: {},
'postcss-nested': {},
},
};This configuration tells PostCSS to first process your CSS using Tailwind, then apply vendor prefixes with Autoprefixer, and finally support nesting rules using postcss-nested.
Nesting allows you to write more readable and organized CSS, similar to SCSS, while still taking advantage of Tailwind’s utility classes. You can include additional PostCSS plugins here based on your project needs.
Final Example Configuration
Here’s a complete tailwind.config.js file that includes all the customizations covered above. You can use this as a base to build your own theme config:
module.exports = {
content: [
"./*.php",
"./template-parts/**/*.php",
"./inc/**/*.php",
"./blocks/**/*.php",
"./js/**/*.js"
],
darkMode: 'class',
safelist: ['bg-blue-500', 'text-center'],
theme: {
extend: {
colors: {
primary: '#1e40af',
secondary: '#64748b',
accent: '#f59e0b',
},
fontFamily: {
sans: ['"Inter"', 'sans-serif'],
serif: ['"Merriweather"', 'serif'],
},
spacing: {
'128': '32rem',
'144': '36rem',
},
screens: {
'xs': '480px',
'3xl': '1920px',
},
zIndex: {
'60': '60',
'70': '70',
},
borderRadius: {
'4xl': '2.5rem',
},
},
},
plugins: [
function ({ addUtilities }) {
addUtilities({
'.text-shadow': { textShadow: '2px 2px #000' },
'.rotate-y-180': { transform: 'rotateY(180deg)' },
});
},
],
}Best Practices for Maintaining Your Tailwind-Powered WordPress Theme
As your WordPress project grows, so will your Tailwind configuration and class usage. To avoid performance issues and keep your styles clean, it’s important to establish a few key practices early in development:
- Review and prune unused custom values: If you’re no longer using a color or font, remove it from
tailwind.config.jsto reduce complexity. - Use component partials: Break large templates into smaller files in a
/template-partsor/blocksfolder. This keeps your structure clear and your config paths organized. - Consider environment-specific builds: You can use a production build command like
NODE_ENV=production npx tailwindcss -i ./src/input.css -o ./dist/output.css --minifyto reduce file size for live sites. - Track class name bloat: Tailwind allows rapid development, but you can easily overuse similar utility classes. Periodically refactor and reuse patterns.
Tailwind CSS is not just about writing fast code. It is about writing consistent, scalable, and performance-aware CSS. The combination of utility-first classes, dark mode support, and full configuration flexibility makes it one of the most developer-friendly tools in WordPress theming today.
Whether you’re building for clients or crafting a custom site from scratch, your tailwind.config.js file is the key to unlocking that power. Don’t treat it as a “set it and forget it” file. Revisit it often, evolve it with your design needs, and keep it organized for long-term maintainability.
Conclusion
Tailwind CSS becomes incredibly powerful when you tailor it to your WordPress project. Whether you’re building a design system, managing dark mode, or optimizing dynamic classes for ACF, your tailwind.config.js file is where it all happens.
As always, if you have questions, feel free to comment below!
