Tailwind CSS Academy · Lesson

Extending vs Overriding the Theme

Use theme.extend to add new values alongside defaults, versus theme to replace defaults entirely, with practical examples for both.

Two Ways to Customize the Theme

When you want to add custom values to Tailwind's design system, you have two choices: extend the defaults or override them. Extending adds your values alongside Tailwind's built-in values. Overriding replaces Tailwind's built-in values with only what you provide. The wrong choice can silently remove utilities you depend on, so understanding the distinction is critical before modifying tailwind.config.js.

What Extending Means

When you place values inside theme.extend, Tailwind merges them with the corresponding default values. The result is the full default set plus your additions. For example, adding a custom color inside theme.extend.colors gives you all of Tailwind's built-in colors (red, blue, green, etc.) AND your custom color. Nothing is lost.

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        // ADDED alongside default colors like red, blue, gray...
        brand: {
          light: '#818cf8',
          DEFAULT: '#6366f1',
          dark: '#4f46e5',
        },
      },
    },
  },
};

// Now you can use BOTH:
// bg-brand-DEFAULT, bg-brand-light, bg-brand-dark (custom)
// bg-blue-500, bg-red-400, bg-gray-100 (still available!)

All lessons in this course

← Back to Tailwind CSS Academy