skip to content

In Tailwind CSS v4, `@theme { --font-display: var(--font-lora), serif; }` makes `font-display` headings render in the default font, though `<body>` sets `--font-lora`; why, and what fixes it?

level: seniorimportance: should knowfreq 9%

answer

  1. where the reference is resolved
  2. theme variables are declared on :root
  3. descendants inherit the computed value
  4. the inline option on @theme
  5. trade-off: value baked into the utility

basics

~20 s

Without the inline option, font-display compiles to var(--font-display), and that variable is computed on :root, where --font-lora does not exist yet. @theme inline puts var(--font-lora) into the utility itself, so it resolves on the heading.

solid answer

~40 s

By default Tailwind CSS v4 writes theme variables to `:root` and makes each utility reference the theme variable, so `font-display` becomes `font-family: var(--font-display)`. The value `var(--font-lora), serif` is computed where `--font-display` is declared, on `:root`, and `--font-lora` is only set on `<body>`, one level down. The reference fails there, `--font-display` becomes invalid, and every heading inherits that failed value, so the declaration falls back to the inherited font. `@theme inline { --font-display: var(--font-lora), serif; }` makes the utility carry the value instead: `font-family: var(--font-lora), serif`, resolved on the heading, which inherits `--font-lora` from `<body>`. Declaring `--font-lora` on `<html>` also fixes it. The cost of `inline`: redefining `--font-display` later, in a scope or under a dark selector, no longer reaches the utility.

code

css · 10 lines
css
@import "tailwindcss";

/* Broken: .font-display { font-family: var(--font-display) }
   and --font-display is computed on :root */
/* @theme { --font-display: var(--font-lora), serif; } */

/* Fixed: .font-display { font-family: var(--font-lora), serif } */
@theme inline {
  --font-display: var(--font-lora), serif;
}

go deeper

for a junior

Recall that a utility normally points at the theme variable with var(), and that @theme inline puts the variable's value into the utility instead.

for a middle

Explain where the theme variable is declared, why a variable set only on body is not visible there, and what the compiled utility looks like with and without inline.

for a senior

Diagnose the silent fallback from DevTools, choose between inline and moving the variable up, and explain why inline breaks overrides of the theme variable itself.

for a principal

Set a convention for when token aliases use inline, so runtime-switched values and overridable tokens do not get mixed in one shared theme.

## The setup A yoga-studio booking app loads its display font through a font loader that sets a custom property, `--font-lora`, on `<body>` through a generated class. The stylesheet maps that into the theme: ```css @theme { --font-display: var(--font-lora), serif; } ``` `font-display` exists as a utility, yet headings that use it render in the page's default sans font. ## What Tailwind emits without `inline` Tailwind CSS v4 handles a theme variable in two places: - **The variable** is written as a custom property on `:root` in the `theme` layer: `--font-display: var(--font-lora), serif;` - **The utility** references the theme variable, not its value: `.font-display { font-family: var(--font-display); }` That indirection is normally a feature: one variable on `:root`, every utility pointing at it. ## Why the font is lost The failure comes from how custom properties work, in one clause: a `var()` inside a custom property's value is substituted on the element where that property is declared, and descendants inherit the result rather than re-evaluating it. Tailwind's theme documentation states the consequence directly: the reference "is resolved where `--font-sans` is defined". Step by step: 1. On `<html>` (`:root`), `--font-display` is computed. `--font-lora` is not defined there, and the `var()` has no fallback of its own, so `--font-display` becomes invalid. 2. `<body>` defines `--font-lora`, but `--font-display` is not recomputed there; it is inherited as already computed. 3. The heading's `font-family: var(--font-display)` receives an invalid value, so the declaration acts as if unset, and `font-family` is inherited — the default font from the base styles. The `, serif` fallback in the value does not help: it is part of the value that failed, not a fallback of `var()`. ## The fix: `@theme inline` ```css @theme inline { --font-display: var(--font-lora), serif; } ``` With the `inline` option the utility uses the theme variable's **value** instead of a reference to it: ```css .font-display { font-family: var(--font-lora), serif; } ``` Now `var(--font-lora)` is resolved on the heading itself, which inherits `--font-lora` from `<body>`. This is the case Tailwind documents for `inline`: a theme variable whose value references another variable. Other options: - Set the font variable on `<html>` rather than `<body>`, so it already exists where `--font-display` is computed. - Put the literal family name in the theme, if the font is not loaded through a variable at all. ## What `inline` costs `inline` changes what the utility depends on, which matters when you want to change a token at runtime: | Declared with | Utility contains | Redefining the theme variable under `.dark` or in a scope | |---|---|---| | `@theme` | `var(--color-surface)` | the utility follows it | | `@theme inline` | the value, such as `var(--surface)` or a literal colour | the utility ignores it | So the rule of thumb: - Use **`@theme inline`** when the token is an alias for a variable set lower in the tree or switched at runtime, such as a font loader's variable or a colour variable flipped by a mode class on a subtree. Then switch the referenced variable, not the theme variable. - Use **plain `@theme`** for literal values you may want to override by redefining the theme variable itself, for example `.dark { --color-surface: … }` when the dark class sits on `<html>`. ## How to diagnose it 1. Inspect the heading in DevTools and read the computed `font-family`. 2. Look at the rule for `.font-display`: does it say `var(--font-display)` or the inlined value? 3. Inspect `:root` and check whether the referenced variable exists at that level. 4. If the referenced variable is defined only on a descendant, either move it up or switch the block to `@theme inline`. The same trap appears with colours: `--color-brand: var(--brand)` in plain `@theme`, with `--brand` set by a class on a section of the page, gives every `bg-brand` the root's value. ## Why the build does not warn you Nothing about the broken version is invalid from Tailwind's point of view. `--font-display` is a well-formed theme variable in the `--font-*` namespace, the `font-display` utility is generated, and the compiled CSS contains both. The failure happens only in the browser, at computed-value time, and only because of where the referenced variable happens to be declared in the document. That is why this bug tends to surface after a refactor that moves a font-loader class from `<html>` to `<body>`, or when a token is first pointed at a variable owned by a component rather than the page root. A team that maps external variables into the theme regularly should treat `@theme inline` as the default for those alias tokens and keep plain `@theme` for literal values.

  • Why is `inline` the wrong choice for a colour token you override with `.dark { --color-surface: … }`?
    With `inline`, `bg-surface` contains the token's value, not `var(--color-surface)`. Redefining `--color-surface` under `.dark` changes the custom property but nothing reads it, so the utility keeps the light value. Either keep plain `@theme` and override the theme variable, or use `inline` with an alias and switch the referenced variable instead.
  • Does `@theme inline` make Tailwind resolve the referenced variable at build time?
    No. Tailwind copies the expression, here `var(--font-lora), serif`, into the utility; the browser still resolves `var(--font-lora)` at runtime, now on the element that uses the class. Only literal values end up literal.

A plain theme variable is a notice pinned in the building's lobby, filled in once from what the lobby knows; every room reads the lobby notice. With inline, each room gets the instruction itself and fills it in from what that room knows.

  • The , serif in the value works as a fallback when --font-lora is missing.
  • Each element re-evaluates var(--font-lora) inside an inherited theme variable.
  • @theme inline resolves the referenced variable to a fixed value at build time.
  • Putting inline on every @theme block is harmless and always safer.
  • The font fails because the font file never loaded.

Assumes Tailwind CSS v4 (4.3.3 checked); @theme and its inline option are v4's CSS-first replacement for the v3 JavaScript theme.