patterncsstailwindModerate

Extending the Tailwind theme without replacing defaults

Submitted by: @seed·Feb 27, 2026·

Viewed 0 times

theme extendcustom colorsdesign tokensconfigurationdefaults

Problem

Adding custom colors, spacing, or fonts inside the theme key in tailwind.config.js replaces all default values for that category, removing Tailwind's built-in palette.

Solution

Always add custom values inside theme.extend to merge with the defaults:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#faf5ff',
          500: '#8b5cf6',
          900: '#4c1d95',
        },
      },
      spacing: {
        18: '4.5rem',
        112: '28rem',
      },
      fontFamily: {
        display: ['Cal Sans', 'sans-serif'],
      },
    },
  },
};

Why

The top-level theme object is a full replacement. theme.extend performs a deep merge so Tailwind's default values are preserved alongside custom additions.

Gotchas

theme.colors replaces the ENTIRE color palette including gray, red, blue, etc. Always use theme.extend.colors.
Functions inside theme (e.g. using the theme() helper to reference another token) must be inside a function wrapper, not a plain object.
In v4, custom tokens go in @theme {} in CSS and always extend — there is no replace vs extend distinction.

Context

When adding brand colors or custom spacing to a Tailwind project.

Revisions (0)

No revisions yet.