Extending the Default Theme
What you'll learn: How to add custom design tokens to Tailwind without losing its built-in utilities.
The Core Idea
Tailwind CSS comes with a comprehensive set of default values—colors, spacing, fonts, and more. But what if you need to add brand-specific colors or custom spacing values? The extend property in your Tailwind configuration lets you add new values alongside the defaults rather than replacing them entirely.
Think of it like adding new spices to a fully stocked spice rack. You're not throwing away the cinnamon and paprika; you're just making room for your special blends.
How It Works
Inside tailwind.config.js, the theme object has two ways to customize values:
- Direct assignment (replaces defaults completely)
- The
extendproperty (adds to defaults)
When you use extend, your custom values merge with Tailwind's built-in theme. For example:
module.exports = {
theme: {
extend: {
colors: {
'brand-blue': '#1e40af',
'brand-gold': '#fbbf24',
},
spacing: {
'128': '32rem',
'144': '36rem',
},
},
},
}
Now you can use bg-brand-blue, text-brand-gold, p-128, and mt-144 in addition to all of Tailwind's default utilities like bg-blue-500 or p-4.
When to Extend vs Replace
Use extend when you want to preserve Tailwind's defaults while adding your own. Only replace directly if you truly want to eliminate the built-in options (rare in most projects).
Key Takeaway: The extend property lets you add custom design tokens to Tailwind's theme without sacrificing the framework's comprehensive defaults, giving you the best of both worlds.