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?
answer
- where the reference is resolved
- theme variables are declared on :root
- descendants inherit the computed value
- the inline option on @theme
- trade-off: value baked into the utility
basics
~20 sWithout 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 sBy 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@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
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.
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.
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.
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.