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:
@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;
}
<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:
@theme {
--color-brand-blue: oklch(0.5 0.2 250);
--color-brand-purple: oklch(0.5 0.2 300);
}
Common Theme Namespaces
Color values for background, text, border utilities--color-primary: #3b82f6;
--color-primary-50: #eff6ff;
Spacing scale for padding, margin, gap utilities--spacing-4: 1rem;
--spacing-128: 32rem;
Font sizes with optional line-height sub-properties--font-size-2xl: 1.5rem;
--font-size-2xl--line-height: 2rem;
Responsive breakpoints for media queries--breakpoint-sm: 40rem;
--breakpoint-md: 48rem;
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;
}
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);
}
@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:
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:
export default {
theme: {
// Completely replaces default colors
colors: {
primary: '#3b82f6',
},
},
}
Best Practices
- Use @theme for CSS-based values - Colors, spacing, and sizes defined close to usage
- Use config for complex logic - Dynamic values, calculations, or conditional themes
- Prefer reference mode for large values - Keep generated CSS size down
- 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.