Theme Customization

Customize your design system using the @theme directive and theme configuration

Tailwind CSS v4 introduces a powerful new way to customize your theme using the @theme directive directly in your CSS, alongside the traditional JavaScript configuration approach.

Using @theme

The @theme directive allows you to define theme values directly in your CSS files:

app.css

@import 'tailwindcss';

@theme {
  --color-primary: #3b82f6;
  --color-secondary: #8b5cf6;
  
  --spacing-18: 4.5rem;
  --spacing-128: 32rem;
  
  --font-size-2xs: 0.625rem;
  --font-size-2xs--line-height: 0.75rem;
}

These values are automatically available as utilities:

<div class="bg-primary text-secondary p-18">
  <p class="text-2xs">Custom themed content</p>
</div>

Theme Namespaces

Theme values are organized into namespaces using CSS custom properties:

Colors

@theme {
  --color-brand-blue: oklch(0.5 0.2 250);
  --color-brand-purple: oklch(0.5 0.2 300);
}

Common Theme Namespaces

--color-* · color

Color values for background, text, border utilities

--color-primary: #3b82f6;
--color-primary-50: #eff6ff;

--spacing-* · length

Spacing scale for padding, margin, gap utilities

--spacing-4: 1rem;
--spacing-128: 32rem;

--font-size-* · length

Font sizes with optional line-height sub-properties

--font-size-2xl: 1.5rem;
--font-size-2xl--line-height: 2rem;

--breakpoint-* · length

Responsive breakpoints for media queries

--breakpoint-sm: 40rem;
--breakpoint-md: 48rem;

--container-* · length

Container query breakpoints

--container-sm: 20rem;
--container-md: 28rem;

Sub-properties

Some theme values support sub-properties using the -- separator:

@theme {
  --font-size-xs: 0.75rem;
  --font-size-xs--line-height: 1rem;
  --font-size-xs--letter-spacing: 0.05em;
}

The text-xs utility will apply all sub-properties:

<!-- Applies font-size, line-height, and letter-spacing -->
<p class="text-xs">Text with complete typography</p>

Reference Mode

Use @theme reference when you want to define theme values that should be available to the configuration but not emitted as CSS variables:

@theme reference {
  --color-brand: #3b82f6;
  --spacing-custom: 2.5rem;
}

Reference theme values are useful for:

• Plugin development where values are transformed
• Keeping the generated CSS smaller
• Defining values used only in JavaScript calculations

Inline vs Variable Resolution

By default, theme values are referenced as CSS variables:

/* Generated CSS */
.bg-primary {
  background-color: var(--color-primary);
}

With @theme reference, values are inlined:

@theme reference {
  --color-primary: #3b82f6;
}

/* Generated CSS */
.bg-primary {
  background-color: #3b82f6;
}

Clearing Theme Values

Set values to initial to remove them:

@theme {
  /* Remove all color values */
  --color-*: initial;
  
  /* Remove specific color */
  --color-red: initial;
  
  /* Remove all theme values */
  --*: initial;
}

JavaScript Configuration

You can also define theme values in your tailwind.config.js:

tailwind.config.ts

export default {
  theme: {
    colors: {
      primary: '#3b82f6',
      secondary: '#8b5cf6',
    },
    spacing: {
      '18': '4.5rem',
      '128': '32rem',
    },
    extend: {
      fontSize: {
        '2xs': ['0.625rem', { lineHeight: '0.75rem' }],
      },
    },
  },
}

Theme Function

Access theme values from within configuration:

export default {
  theme: {
    borderRadius: {
      DEFAULT: '0.25rem',
    },
    extend: {
      spacing: ({ theme }) => ({
        'safe-top': theme('spacing.4'),
      }),
      borderRadius: ({ theme }) => ({
        '4xl': `calc(${theme('borderRadius.DEFAULT')} * 4)`,
      }),
    },
  },
}

Merging Strategies

When using extend, theme values are deeply merged:

Replace

export default {
  theme: {
    // Completely replaces default colors
    colors: {
      primary: '#3b82f6',
    },
  },
}

Best Practices

1. Use @theme for CSS-based values - Colors, spacing, and sizes defined close to usage
2. Use config for complex logic - Dynamic values, calculations, or conditional themes
3. Prefer reference mode for large values - Keep generated CSS size down
4. Use sub-properties - Group related values like font-size and line-height

Be cautious when clearing theme values with --*: initial - this removes ALL theme values and should only be used when you want complete control over the entire design system.