How do I extend the default theme in Tailwind?

Based on the repository data, you extend the default theme in Tailwind using the extend property in your theme configuration.

Here's how it works:

Basic Theme Extension:

You define an extend object within your theme configuration. For example, to add a custom color while keeping the defaults:

{
  theme: {
    extend: {
      colors: {
        blue: 'blue',
      },
    },
  },
}

This approach merges your custom values with the default theme values rather than replacing them entirely.

Nested Theme Values:

The same pattern applies to nested theme properties. For instance, if you want to extend colors with nested values:

{
  theme: {
    extend: {
      colors: {
        blue: {
          600: '#2563eb',
        },
      },
    },
  },
}

Function-Based Extensions:

Theme values can also reference other theme values using a function. For example [packages/tailwindcss/src/compat/default-theme.ts:L887-L926], some default theme keys like scrollMargin are defined as:

scrollMargin: ({ theme }) => theme('spacing'),

This allows extended theme keys to derive from other theme keys dynamically.

Key Concept:

When you use extend, your custom values are merged with (not replacing) the default theme, so you keep all default utilities plus your custom additions [packages/tailwindcss/src/compat/apply-config-to-theme.test.ts:L176-L215].

FOLLOW_UPS:

• How do I completely replace the default theme?
• Can theme values reference other custom theme values?
• What's the difference between theme and extend?