Theme Variable Reference

Every @theme namespace in Tailwind v4 — the utilities each generates, the full default scales, and how to extend, override, disable and read them.

Theme variables are CSS custom properties declared inside @theme. A variable's namespace — the part before the last segment — decides which utilities it generates. Everything on this page is a real default in Tailwind v4.

Namespace summary#

Two variables are not namespaces but scalars in their own right:

--color-*#

The default palette has 22 families, each with eleven steps — 50 100 200 300 400 500 600 700 800 900 950:

Plus --color-black: #000 and --color-white: #fff. The keywords transparent, current and inherit are built in and are not theme variables.

Every family is defined in oklch(), which is why the shade ramps stay perceptually even and why bg-sky-500/40 mixes predictably.

@theme {
  --color-brand-50:  oklch(0.97 0.02 264);
  --color-brand-500: oklch(0.62 0.19 264);
  --color-brand-900: oklch(0.35 0.14 264);
}

One --color-* entry generates bg-*, text-*, border-*, outline-*, ring-*, inset-ring-*, shadow-*, inset-shadow-*, drop-shadow-*, text-shadow-*, divide-*, decoration-*, accent-*, caret-*, fill-*, stroke-*, from-*, via-*, to-*, placeholder-*, selection-*, marker-* and the scrollbar-thumb-* / scrollbar-track-* pair.

--font-*#

--font-* accepts two sub-properties:

@theme {
  --font-display: "Satoshi", ui-sans-serif, sans-serif;
  --font-display--font-feature-settings: "cv02", "cv03";
  --font-display--font-variation-settings: "opsz" 32;
}

font-display then sets all three declarations at once.

--text-*#

Each size ships with a paired line height.

Sub-property syntax#

A second -- suffix attaches a companion declaration to a font-size token:

@theme {
  --text-hero: 4rem;
  --text-hero--line-height: 1.05;
  --text-hero--letter-spacing: -0.02em;
  --text-hero--font-weight: 700;
}

<h1 class="text-hero">Sets size, leading, tracking and weight.</h1>

Override any of them inline — text-hero leading-tight wins, because the explicit utility comes later in the cascade. The text-<size>/<number> shorthand does the same for line height: text-hero/none, text-sm/6.

--font-weight-*#

--tracking-*#

--leading-*#

leading-none is a static utility for line-height: 1 and has no theme variable. Numeric leading-<number> utilities are derived from --spacing: leading-7 is calc(var(--spacing) * 7).

--spacing#

@theme {
  --spacing: 0.25rem;
}

One variable drives p-*, m-*, gap-*, space-*, w-*, h-*, size-*, inset-*, translate-*, leading-<number>, indent-* and more. p-4 compiles to calc(var(--spacing) * 4), so changing --spacing rescales the whole system proportionally.

Values are generated on demand — p-13, mt-96 and gap-7 all work without configuration.

Named spacing tokens live in the --spacing-* namespace:

@theme {
  --spacing-gutter: 1.5rem;
}

<div class="px-gutter gap-gutter">…</div>

--breakpoint-*#

Adding --breakpoint-3xl: 120rem creates 3xl: and max-3xl: at once. The container utility also reads this namespace.

--container-*#

This namespace does double duty: it sizes max-w-* and it defines the container query variants @3xs: through @7xl: and their @max-* counterparts.

--radius-*#

rounded-none (0) and rounded-full (calc(infinity * 1px)) are static utilities with no variable.

--shadow-* and friends#

shadow-none, inset-shadow-none and text-shadow-none are static resets.

--blur-*#

One entry generates two utilities: blur-* and backdrop-blur-*.

--perspective-*#

Smaller values sit the camera closer and exaggerate the effect. perspective-none is static.

--aspect-*#

aspect-square (1 / 1) and aspect-auto are static, and any ratio works inline: aspect-3/2, aspect-21/9.

--ease-*#

ease-linear and ease-initial are static utilities.

--animate-*#

Define keyframes inside @theme so they travel with the token:

@theme {
  --animate-wiggle: wiggle 1s ease-in-out infinite;

  @keyframes wiggle {
    0%, 100% { transform: rotate(-3deg); }
    50%      { transform: rotate(3deg); }
  }
}

--tab-size-* and --zoom-*#

v4.3 Both namespaces ship empty. tab-<number> and zoom-<number> work out of the box from bare values; the namespaces exist so you can name the ones you use repeatedly.

@theme {
  --tab-size-github: 8;
  --zoom-compact: 0.85;
}

<pre class="tab-github">…</pre>
<div class="zoom-compact">…</div>

Default variables#

These are not namespaces. They set base values the preflight and a few utilities read.

Change --default-transition-duration to retune every bare transition in the project at once.

Extending and overriding#

Add a token#

@import "tailwindcss";

@theme {
  --font-poppins: Poppins, sans-serif;
}

New utility, defaults untouched.

Override one default#

@theme {
  --breakpoint-sm: 30rem;
}

Remove one default#

@theme {
  --breakpoint-2xl: initial;
}

2xl: and max-2xl: stop existing.

Replace an entire namespace#

@theme {
  --color-*: initial;
  --color-white: #fff;
  --color-purple: #3f3cbb;
  --color-midnight: #121063;
  --color-tahiti: #3ab7bf;
  --color-bermuda: #78dcca;
}

bg-red-500 no longer compiles. This is the cleanest way to enforce a closed palette — a typo becomes a build-visible missing class rather than a plausible-looking wrong colour.

Start from nothing#

@theme {
  --*: initial;
  --spacing: 4px;
  --font-body: Inter, sans-serif;
  --color-lagoon: oklch(0.72 0.11 221.19);
  --color-coral: oklch(0.74 0.17 40.24);
}

@theme inline#

By default a utility references the variable: .font-sans { font-family: var(--font-sans) }. If --font-sans itself holds var(--font-inter), that indirection is captured where @theme was declared, so a value set later on a wrapper element never reaches it.

inline resolves the reference at build time and emits the inner variable directly:

@theme inline {
  --font-sans: var(--font-inter);
}

.font-sans {
  font-family: var(--font-inter);
}

Use it for any token whose value is a runtime variable — Next.js font loading and semantic colour aliases that flip between light and dark are the two common cases.

@theme static#

Tailwind only emits the CSS variables that some utility actually uses. static emits every variable in the block regardless:

@theme static {
  --color-chart-1: oklch(0.7 0.15 200);
  --color-chart-2: oklch(0.7 0.15 30);
}

Reach for it when JavaScript reads a token no class references — chart palettes, canvas rendering, animation libraries.

Referencing tokens outside utilities#

In custom CSS#

@layer components {
  .prose-callout {
    border-left: 3px solid var(--color-brand-500);
    padding-inline: --spacing(4);
    font-size: var(--text-sm);
    color: --alpha(var(--color-gray-950) / 10%);
  }
}

--spacing(4) expands to calc(var(--spacing) * 4); --alpha() compiles to a color-mix().

In arbitrary values#

<div class="rounded-[calc(var(--radius-xl)-1px)]">…</div>

With the shorthand syntax#

<div class="bg-(--color-brand-500) p-(--gutter)">…</div>

bg-(--x) is exactly bg-[var(--x)].

In inline styles#

<div style="background-color: var(--color-brand-500)">…</div>

In JavaScript#

const styles = getComputedStyle(document.documentElement)
const shadow = styles.getPropertyValue('--shadow-xl')

<motion.div animate={{ backgroundColor: 'var(--color-brand-500)' }} />

Passing the var() string is preferable to reading the computed value — it keeps the animation live across a theme change.

Common mistakes#

• Declaring tokens in :root instead of @theme. A plain custom property produces a variable but no utility.
• Inventing a namespace. --brand-color, --size-* and --space-* generate nothing. Only the namespaces in the table above are recognised.
• Putting @theme before @import "tailwindcss". The import has to come first.
• Forgetting inline for runtime variables. The classic symptom is a webfont that never applies.
• Expecting getPropertyValue to find an unused token. Wrap it in @theme static, or reference it from at least one class.
• Using theme() in new code. theme(spacing.12) still works but is deprecated — use var(--spacing) and --spacing().

Related topics#

• Theme & Design Tokens — the same system with worked examples
• Colors — the palette in practice
• Custom Utilities — turning namespaces into new utilities with @utility
• Functions & Directives — --alpha(), --spacing(), --theme(), @config
• Cheat Sheet — the utilities these tokens generate