@theme directive for customizing design tokens
In Tailwind CSS v4, customize your theme (colors, fonts, breakpoints, spacing, easing, etc.) using the @theme directive directly in CSS instead of tailwind.config.js. Example:
@theme {
--font-display: "Satoshi", "sans-serif";
--breakpoint-3xl: 120rem;
--color-avocado-100: oklch(0.99 0 0);
--color-avocado-200: oklch(0.98 0.04 113.22);
--color-avocado-300: oklch(0.94 0.11 115.03);
--color-avocado-400: oklch(0.92 0.19 114.08);
--color-avocado-500: oklch(0.84 0.18 117.33);
--color-avocado-600: oklch(0.53 0.12 118.34);
--ease-fluid: cubic-bezier(0.3, 0, 0, 1);
--ease-snappy: cubic-bezier(0.2, 0, 0, 1);
}
Theme variables become CSS custom properties accessible via var().
Customizing theme animation with --animate-* and @theme
To add a custom named animation utility, define a CSS variable prefixed with `--animate-` inside an `@theme` block, and include the corresponding `@keyframes` definition nested inside the same `@theme` block. Example: `@theme { --animate-wiggle: wiggle 1s ease-in-out infinite; @keyframes wiggle { 0%, 100% { transform: rotate(-3deg); } 50% { transform: rotate(3deg); } } }`. This makes the utility `animate-wiggle` available, which resolves to `animation: var(--animate-wiggle);`.
Customizing aspect-ratio theme values
You can add custom named aspect ratios in the theme, e.g. defining a custom name 'retro' with value '4 / 3' allows using a utility like aspect-retro. In Tailwind v4 this is done via the @theme directive using a CSS variable such as --aspect-retro: 4 / 3; in your CSS, rather than editing tailwind.config.js.
customizing shadow colors in theme
Shadow, inset-shadow, ring, and inset-ring colors can be customized through the theme configuration.
customizing theme shadows
Box shadow values can be customized in the theme configuration under the shadow key. For example, adding a custom 3xl shadow with value 0 35px 35px rgba(0, 0, 0, 0.25).
customizing theme inset shadows
Inset shadow values can be customized in the theme configuration under the inset-shadow key. For example, adding a custom md inset shadow with value inset 0 2px 3px rgba(0, 0, 0, 0.25).
Default color palette steps
Every color in the default palette includes 11 steps, with 50 being the lightest and 950 being the darkest. The steps are: 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950.
Default color palette in OKLCH format
The default Tailwind color palette is defined using OKLCH color space. Red palette: --color-red-50 through --color-red-950. Orange palette: --color-orange-50 through --color-orange-950. Yellow palette: --color-yellow-50 through --color-yellow-950. Lime palette: --color-lime-50 through --color-lime-950. Green palette: --color-green-50 through --color-green-950. Emerald palette: --color-emerald-50 through --color-emerald-950. Teal palette: --color-teal-50 through --color-teal-950. Cyan palette: --color-cyan-50 through --color-cyan-950. Sky palette: --color-sky-50 through --color-sky-950. Blue palette: --color-blue-50 through --color-blue-950. Indigo palette: --color-indigo-50 through --color-indigo-950. Violet palette: --color-violet-50 through --color-violet-950. Purple palette: --color-purple-50 through --color-purple-950. Fuchsia palette: --color-fuchsia-50 through --color-fuchsia-950. Pink palette: --color-pink-50 through --color-pink-950. Rose palette: --color-rose-50 through --color-rose-950. Slate palette: --color-slate-50 through --color-slate-950. Gray palette: --color-gray-50 through --color-gray-950. Zinc palette: --color-zinc-50 through --color-zinc-950. Neutral palette: --color-neutral-50 through --color-neutral-950. Stone palette: --color-stone-50 through --color-stone-950. Mauve palette: --color-mauve-50 through --color-mauve-950. Olive palette: --color-olive-50 through --color-olive-950. Mist palette: --color-mist-50 through --color-mist-950. Taupe palette: --color-taupe-50 through --color-taupe-950. Grayscale colors: --color-black and --color-white.
Customizing columns theme with container key
The columns utility can be customized in the theme configuration using the 'container' theme key. Custom columns sizes can be added by extending the container theme values.
Custom font family theme configuration
Custom font families can be defined in the @theme block using CSS custom properties like --font-roboto: "Roboto", sans-serif; and then referenced with utility classes like font-roboto.
Default breakpoint values
Default responsive breakpoints are: --breakpoint-sm: 40rem, --breakpoint-md: 48rem, --breakpoint-lg: 64rem, --breakpoint-xl: 80rem, --breakpoint-2xl: 96rem.
Theme variable namespaces list
Theme variable namespaces determine which utility classes and variants exist. The namespaces are: --color-* (color utilities like bg-red-500, text-sky-300), --font-* (font family utilities like font-sans), --text-* (font size utilities like text-xl), --font-weight-* (font weight utilities like font-bold), --tracking-* (letter spacing utilities like tracking-wide), --leading-* (line height utilities like leading-tight), --tab-size-* (tab size utilities like tab-github), --breakpoint-* (responsive breakpoint variants like sm:*), --container-* (container query variants like @sm:* and size utilities like max-w-md), --spacing-* (spacing and sizing utilities like px-4, max-h-16), --radius-* (border radius utilities like rounded-sm), --shadow-* (box shadow utilities like shadow-md), --inset-shadow-* (inset box shadow utilities like inset-shadow-xs), --drop-shadow-* (drop shadow filter utilities like drop-shadow-md), --blur-* (blur filter utilities like blur-md), --perspective-* (perspective utilities like perspective-near), --zoom-* (zoom utilities like zoom-compact), --aspect-* (aspect ratio utilities like aspect-video), --ease-* (transition timing function utilities like ease-out), --animate-* (animation utilities like animate-spin).
Default color palette uses OKLCH color space
All default colors in Tailwind v4 are defined using the oklch() color function. For example, --color-red-50: oklch(0.971 0.013 17.38); defines a red color with lightness 97.1%, chroma 0.013, and hue 17.38 degrees.
Default typography scale variables
Font size variables use --text-* naming with corresponding line-height variables. For example, --text-base: 1rem and --text-base--line-height: calc(1.5 / 1). Font weights use --font-weight-* (thin to black: 100, 200, 300, 400, 500, 600, 700, 800, 900). Letter spacing uses --tracking-* (tighter to widest), and line height uses --leading-* (tight to loose).
Default spacing scale value
The default spacing scale is set to --spacing: 0.25rem, which serves as the base unit for all spacing and sizing utilities.
Default container query sizes
Container query sizes are defined from --container-3xs: 16rem through --container-7xl: 80rem, providing ten container sizes for container queries.
Default border radius values
Border radius variables range from --radius-xs: 0.125rem to --radius-4xl: 2rem, providing eight size options for border-radius utilities.
Default shadow values
Box shadow variables include --shadow-2xs through --shadow-2xl. Inset shadows include --inset-shadow-2xs through --inset-shadow-sm. Drop shadows include --drop-shadow-xs through --drop-shadow-2xl. Text shadows include --text-shadow-2xs through --text-shadow-lg.
Default blur filter values
Blur filter variables range from --blur-xs: 4px to --blur-3xl: 64px, providing seven blur size options.
Default perspective values
Perspective variables include --perspective-dramatic: 100px, --perspective-near: 300px, --perspective-normal: 500px, --perspective-midrange: 800px, and --perspective-distant: 1200px.
Default animation values
Default animations are --animate-spin: spin 1s linear infinite, --animate-ping: ping 1s cubic-bezier(0, 0, 0.2, 1) infinite, --animate-pulse: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite, and --animate-bounce: bounce 1s infinite. Corresponding @keyframes are defined for each animation.
Default timing function values
Easing function variables are --ease-in: cubic-bezier(0.4, 0, 1, 1), --ease-out: cubic-bezier(0, 0, 0.2, 1), and --ease-in-out: cubic-bezier(0.4, 0, 0.2, 1).
Default aspect ratio value
The default aspect ratio variable is --aspect-video: 16 / 9.
Customizing transition timing function in theme
You can customize transition timing function values in your Tailwind CSS theme configuration by adding custom easing curves that become available as utility classes.
Customizing font size with additional text properties
In the @theme directive, you can customize font size by setting --text-<name> and optionally provide default --text-<name>--line-height, --text-<name>--letter-spacing, and --text-<name>--font-weight values. For example: @theme { --text-tiny: 0.625rem; --text-tiny--line-height: 1.5rem; --text-tiny--letter-spacing: 0.125rem; --text-tiny--font-weight: 500; }
Font-variation-settings configuration example in v3.3
```javascript
// tailwind.config.js
module.exports = {
theme: {
fontFamily: {
sans: [
"Inter var, sans-serif",
{
fontFeatureSettings: '"cv11", "ss01"',
fontVariationSettings: '"opsz" 32',
},
],
},
},
};
```
This example configures the Inter font with optical size axis set to 32, which triggers the Display variation optimized for larger sizes like headlines.
Font-variation-settings configuration in v3.3
Tailwind CSS v3.3 added support for configuring font-variation-settings for custom font families. In the tailwind.config.js theme.fontFamily configuration, after the font list, you can provide an options object with fontVariationSettings property. This allows you to set font variation settings directly on the font-* utilities.
Tailwind CSS v4.2 new color palettes
Tailwind CSS v4.2 added four new color palettes to the default theme: mauve, olive, mist, and taupe. These are neutral-adjacent palettes that provide distinct alternatives to the existing gray, zinc, neutral, stone, and slate palettes. Each palette includes shades 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, and 950.
New color palettes available in v4.2: mauve, olive, mist, taupe
The four new color palettes added in v4.2 are all neutral-adjacent palettes: mauve (slightly purple-tinted neutral), olive (green-tinted neutral), mist (cool-tinted neutral), and taupe (warm-tinted neutral). They provide warmer, cooler, greener, or other personality-driven alternatives to existing gray palettes when you want the whole design to lean in a particular direction.
New color utilities in v4.2: mauve, olive, mist, taupe usage
Examples of using new palettes: <div class="bg-mauve-950 text-mauve-100 ...">Mauve</div>, <div class="bg-olive-100 text-olive-950 ...">Olive</div>, <div class="border border-mist-200 shadow-taupe-950/10 ...">Mist and taupe</div>. Each palette provides the same shade range (50-950) as existing color palettes.
scroll-padding utilities customization via spacing scale
The scroll-padding utilities (scroll-p, scroll-px, scroll-py, scroll-ps, scroll-pe, scroll-pbs, scroll-pbe, scroll-pt, scroll-pr, scroll-pb, scroll-pl) can be customized through the theme's spacing scale configuration.