skip to content

Theme Variables

@theme declares tokens as CSS variables in namespaces like --color-* and --spacing, each generating utilities; arbitrary values cover one-offs. Interviewers ask how to extend or replace the theme.

on this pageshow

questions

6

In Tailwind CSS v4, what is a theme variable, and how does declaring one in `@theme` differ from declaring a plain `:root` variable?

level: juniorimportance: must knowfreq 26%

answer

  1. configuration lives in the stylesheet
  2. the name's prefix picks a utility family
  3. which declarations create classes
  4. compiled output: :root in the theme layer
  5. only used variables emitted; @theme static

basics

~20 s

A theme variable is a custom property declared inside @theme in Tailwind CSS v4; its namespace, such as --color-* or --font-*, makes Tailwind generate matching utilities. A variable on :root is plain CSS and generates no utility class.

solid answer

~40 s

In Tailwind CSS v4 the theme lives in the stylesheet. Declaring `--color-lotus-500: oklch(0.68 0.14 350)` inside `@theme` does two things: Tailwind emits it as an ordinary custom property in the compiled CSS (on `:root`, inside the `theme` cascade layer), and, because the name sits in the `--color-*` namespace, it makes `bg-lotus-500`, `text-lotus-500`, `border-lotus-500` and the other colour utilities available. The namespace decides the family: `--font-*` drives `font-*`, `--breakpoint-*` drives responsive variants such as `3xl:`. A variable declared on `:root` is just CSS: usable through `var()`, but no class is generated for it, which is the right choice for values that should not become utilities. `@theme` must sit at the top level, not inside a selector or media query.

code

css · 16 lines
css
@import "tailwindcss";

@theme {
  --color-lotus-500: oklch(0.68 0.14 350);
  --font-display: "Fraunces", serif;
  --breakpoint-3xl: 120rem;
}

:root {
  --booking-panel-max: 42rem;
}

.booking-panel {
  max-width: var(--booking-panel-max);
  border-color: var(--color-lotus-500);
}

go deeper

for a junior

Recall that a theme variable is a custom property inside @theme, that its prefix such as --color- or --font- decides which utilities appear, and that a :root variable gets no class.

for a middle

Explain the namespace table, that theme variables compile to custom properties on :root in the theme layer, and that utilities reference them with var() instead of copying values.

for a senior

Show you know the output is pruned to used variables, when @theme static is needed, and why @theme must be top-level, including what to do instead for dark-mode values.

for a principal

Weigh which values deserve to be tokens with utilities and which stay plain custom properties, since every theme variable widens the class vocabulary a whole codebase can use.

## What a theme variable is In Tailwind CSS v4 you configure the framework in CSS, not in a JavaScript file. A **theme variable** is a CSS custom property declared inside the `@theme` directive: ```css @import "tailwindcss"; @theme { --color-lotus-500: oklch(0.68 0.14 350); } ``` Tailwind's documentation calls these the project's design tokens. A theme variable is a custom property and also an instruction to the compiler: "a utility class should exist for this value". After the block above, `bg-lotus-500`, `text-lotus-500` and `fill-lotus-500` exist, and once something uses the token the compiled CSS also contains `--color-lotus-500` as a normal custom property you can reference with `var()`. ## Namespaces decide which utilities exist The part of the name before your own suffix is the **namespace**, and each namespace feeds one or more utility or variant families. A few of the defaults: | Namespace | What it generates | Example | |---|---|---| | `--color-*` | colour utilities | `bg-lotus-500`, `text-lotus-500` | | `--font-*` | font-family utilities | `font-display` | | `--text-*` | font-size utilities | `text-xl` | | `--spacing` | the base unit numeric spacing and sizing utilities multiply | `p-4`, `mt-7` | | `--breakpoint-*` | responsive variants | `3xl:grid-cols-6` | | `--container-*` | container-query variants and size utilities | `@sm:`, `max-w-md` | | `--radius-*` | border-radius utilities | `rounded-sm` | Two consequences follow: - A variable inside `@theme` whose name does not match a namespace is still a custom property that `var()` can read, but no utility appears for it. - Utilities such as `flex` or `pointer-events-none` are static and exist in every project; `bg-red-200` or `shadow-sm` exist only because the default `theme.css` that `@import "tailwindcss"` pulls in declares the matching variables. ## `@theme` versus `:root` Both blocks hold custom properties, and both end up as custom properties in the browser. The difference is what the compiler does with them: - **`@theme`** — the variable becomes a token: utilities (or variants) are generated from it, and it is written to the output. - **`:root`** — the variable is ordinary CSS: Tailwind leaves it alone, and only `var()` can use it. Tailwind's documentation recommends exactly this split: `@theme` for a token that should map to a utility, `:root` for a variable that should not have one, such as a layout measurement used in a single component rule. The special syntax also lets Tailwind enforce a rule: theme variables must be declared at the **top level**, never nested under a selector or a media query. ## What the compiled CSS contains When the stylesheet compiles, the theme variables are written as custom properties on `:root` (the source also adds `:host`, so they reach shadow roots) inside the `theme` cascade layer — the first of the four layers `theme, base, components, utilities` that Tailwind's `index.css` declares. A utility then references the variable rather than copying its value, for example `background-color: var(--color-lotus-500)`. By default **only the variables that are used** are emitted: those a generated utility or your own CSS references, or whose full name appears in a scanned source file. The `static` option (`@theme static { … }`, added in 4.0.5) emits every variable in that block regardless, which matters when code reads a token whose name the scanner cannot see, such as a name assembled at runtime. ## Using theme values outside utilities Because tokens compile to custom properties, the same value is available everywhere: 1. In your own CSS: `border-color: var(--color-lotus-500);` 2. In an inline style or an arbitrary value: `rounded-[calc(var(--radius-xl)-1px)]` 3. From JavaScript: `getComputedStyle(document.documentElement).getPropertyValue("--color-lotus-500")` This replaces v3's `resolveConfig` helper, which v4 removed. ## A worked example A yoga-studio booking app moves its brand into the theme. The stylesheet declares `--color-lotus-500`, `--font-display` and `--breakpoint-3xl` inside `@theme`, and keeps `--booking-panel-max` on `:root` because only one component rule uses it. In the markup, a class card uses: ```html <article class="bg-lotus-500 font-display 3xl:grid-cols-6">…</article> ``` What the build produces: - a `.bg-lotus-500` rule whose value is `var(--color-lotus-500)`; - a `.font-display` rule pointing at `var(--font-display)`; - a `3xl:` rule wrapped in a media query at `120rem`; - `--color-lotus-500` and `--font-display` declared on `:root` in the theme layer, because utilities use them; - `--booking-panel-max` exactly where you wrote it, untouched. If someone writes `bg-booking-panel-max`, nothing is generated, because that name was never a theme variable. That is the practical test of the difference: a theme variable is an entry in the utility vocabulary, while a `:root` variable is a value only `var()` can reach. ## Common mistakes 1. Declaring brand colours on `:root` and then wondering why `bg-lotus-500` produces nothing. 2. Naming a token outside a namespace (`--lotus-500`) and expecting colour utilities. 3. Nesting `@theme` inside `.dark` or a media query to make a dark palette; to change a value in dark mode, redefine the emitted custom property under the dark selector instead. 4. Assuming every default variable ships in the CSS; unused ones are pruned unless `@theme static` is used.

  • A class-booking widget reads `--color-lotus-500` with `getComputedStyle` and gets an empty string. No utility uses the colour. Why?
    Tailwind CSS v4 emits only the theme variables that are used: referenced by a generated utility or your CSS, or whose full name appears in a scanned source file. If the widget assembles the name at runtime, or lives outside the scanned files, the variable is pruned. Declaring the tokens in `@theme static { … }` emits every variable in that block regardless of use.
  • Can you put `@theme` inside a `.dark` selector to give dark mode its own palette?
    No. Theme variables must be declared at the top level, not under a selector or media query. Utilities reference the variable, for example `var(--color-surface)`, so you change the value for dark mode by redefining the emitted custom property under the dark selector, such as `.dark { --color-surface: … }` in your base styles.
  • Why does Tailwind CSS v4 not simply turn every `:root` variable into a utility?
    Because not every variable is a token. Layout measurements, component-local values and values set from JavaScript would flood the utility list. `@theme` makes the intent explicit, lets Tailwind enforce top-level declaration, and keeps plain custom properties as plain CSS.

  • Any CSS variable declared on :root automatically becomes a Tailwind utility.
  • Theme variables exist only at build time and cannot be read with var().
  • Every default theme variable is always written to the compiled CSS.
  • Adding a colour in v4 still requires editing tailwind.config.js.
  • @theme can be nested inside a media query or a .dark selector.
  • A token named --lotus-500 inside @theme produces bg-lotus-500.

Assumes Tailwind CSS v4 (4.3.3 checked); v4 replaced the v3 JavaScript theme config with CSS-first @theme variables.

open as a page

In Tailwind CSS v4, how do you extend, override or completely replace a default theme namespace such as the colour palette or the breakpoints?

level: middleimportance: must knowfreq 19%

basics

~20 s

In Tailwind CSS v4, add a variable to extend a namespace, redeclare a default to override it, set one to initial to remove it, and write --color-: initial (or --: initial for everything) before your values to replace it.

open as a page

In Tailwind CSS v4, how do you apply a one-off value the theme lacks: a hex colour, a CSS variable, or an unsupported property?

level: middleimportance: should knowfreq 18%

basics

~10 s

Tailwind CSS v4 accepts arbitrary values in square brackets, such as bg-[#316ff6] or top-[117px]; a CSS variable uses parentheses, bg-(--promo); a property with no utility is written as [mask-type:luminance]. Spaces become underscores.

open as a page

In Tailwind CSS v4, `dark:` utilities follow the OS setting although `<html>` has `class="dark"`; why, and how do you make them follow the class?

level: middleimportance: should knowfreq 15%

basics

~20 s

Tailwind CSS v4's dark variant uses the prefers-color-scheme media query by default, so a dark class does nothing. Override it in CSS with @custom-variant dark (&:where(.dark, .dark *)); a data attribute works the same way.

open as a page

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%

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.

open as a page

When upgrading a Tailwind CSS v3 project with a `tailwind.config.js` to v4, what happens to the config's theme, and when do you keep the file through `@config`?

level: seniorimportance: nice to knowfreq 6%

basics

~20 s

Tailwind CSS v4 no longer detects tailwind.config.js. The upgrade tool converts a simple config to @theme variables; a config with presets, unknown keys or plugins it cannot read is kept and loaded with @config, minus options like safelist and corePlugins.

open as a page