In Tailwind CSS v4, what is a theme variable, and how does declaring one in `@theme` differ from declaring a plain `:root` variable?
answer
- configuration lives in the stylesheet
- the name's prefix picks a utility family
- which declarations create classes
- compiled output: :root in the theme layer
- only used variables emitted; @theme static
basics
~20 sA 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 sIn 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@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
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.
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.
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.
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.