skip to content

Layers & Directives

Tailwind v4 emits native cascade layers; your CSS joins them with @layer, @apply inlines utilities and @reference serves component style blocks. Interviewers ask when @apply backfires.

on this pageshow

questions

6

In Tailwind CSS v4, what does the `@apply` directive do to your CSS rule, and when does reaching for it backfire?

level: juniorimportance: must knowfreq 22%

answer

  1. copied, not referenced
  2. known utilities only
  3. variants become nested rules
  4. Tailwind's sort, not your list
  5. the rule's layer decides

basics

~20 s

In Tailwind CSS v4, @apply copies the declarations of existing utilities into your own rule at build time. It backfires when it rebuilds semantic classes, hides states from the markup, or lands outside a layer where utilities can no longer override it.

solid answer

~40 s

`@apply rounded-lg bg-sky-700 px-4 hover:bg-sky-800` is replaced at build time by the declarations those utilities generate, and a variant becomes a nested rule — `&:hover` inside `@media (hover: hover)`. It only resolves utilities Tailwind knows, built-in or registered with `@utility`, so in v4 a class you wrote yourself in `@layer components` fails with `Cannot apply unknown utility class`. The declarations come out in Tailwind's own sort order, not the order you listed. It backfires three ways: a `.card` rebuilt from `@apply` takes the styling out of the markup and brings naming back; `hover:` and `dark:` states end up in a stylesheet nobody reads beside the template; and a rule outside any layer stops every utility on the element from overriding it.

go deeper

for a junior

Recall that @apply copies the declarations of the listed utilities into your own rule at build time, and that variants such as hover: can be included in the list.

for a middle

Explain what @apply accepts in v4 — built-in and @utility utilities, not your own classes — and why the declarations come out in Tailwind's sort order rather than the order you listed.

for a senior

Show when @apply backfires: rebuilt semantic classes, states hidden from the markup, unlayered rules that beat utilities, and many separately compiled style blocks slowing the build.

for a principal

Decide the team rule for @apply — allowed for CMS or third-party markup inside the components layer, discouraged elsewhere — weighing co-located styling against shared class names across teams.

## What `@apply` does `@apply` is a Tailwind directive used **inside a rule** in your own CSS. At build time **Tailwind CSS v4** compiles each listed class exactly as it would for the markup, then replaces the `@apply` line with the resulting declarations. Nothing refers back to the utility class at runtime; the declarations are copied into your rule. ```css .btn { @apply rounded-lg bg-sky-700 px-4 hover:bg-sky-800; } /* becomes, before Tailwind flattens the nesting */ .btn { border-radius: var(--radius-lg); background-color: var(--color-sky-700); padding-inline: calc(var(--spacing) * 4); &:hover { @media (hover: hover) { background-color: var(--color-sky-800); } } } ``` A variant in the list becomes a nested rule carrying the same condition the prefix gets in markup — in v4, `hover:` only applies on devices that can hover. ## What `@apply` accepts, and what it rejects - **Built-in utilities**, including arbitrary values (`@apply top-[117px]`) and variants (`@apply md:px-6`). - **Custom utilities** registered with `@utility`. - **Not your own classes.** A `.card` written in `@layer components` is ordinary CSS in v4, so `@apply card` fails with `Cannot apply unknown utility class`. v3 allowed it, because v3 treated classes in `@layer components` as utilities. - **Not inside `@keyframes`** — the build errors. - **Only what this compile can see.** A Vue or Svelte style block or a CSS Module is compiled separately and needs `@reference` before its `@apply` rules can resolve the theme. - **Not the global important flag.** Since 4.1.12, `@import "tailwindcss" important` no longer marks applied declarations `!important`; the class-level modifier (`@apply bg-red-700!`) still does. ## The ordering surprise Tailwind sorts the compiled declarations by variant and then by its own property order — **not** by the order you listed the classes. That matters when two classes touch overlapping properties: ```css .chip { @apply px-6 p-2; } ``` Many people expect the later `p-2` to win. Tailwind emits `padding` before `padding-inline`, so the inline padding from `px-6` (1.5rem) survives and only the block padding ends up 0.5rem. In markup the same pair resolves the same way: the rule later in the generated stylesheet wins, never the class later in the attribute. ## When `@apply` backfires | Pattern | What goes wrong | |---|---| | Rebuilding semantic classes (`.card-header`, `.card-body` …) from utilities | The styling leaves the markup again, you are back to naming things, and the same declarations are copied into every rule | | Moving `hover:`, `dark:` or `md:` into `@apply` | The states are no longer visible where the element is written, so a reviewer of the template cannot see them | | `@apply` in an unlayered rule | The copied declarations are unlayered, so every utility on the element stops overriding them | | Relying on list order to settle a conflict | Tailwind's sort decides, as shown above | | `@apply` across dozens of component style blocks | Each block is a separate Tailwind run, and builds slow down | Whether to extract a component at all is a strategy question with its own answer; this table is only about what the directive itself does. ## Reading the build errors `@apply` fails at build time rather than shipping half a rule, and the messages point at the cause: - **`Cannot apply unknown utility class`** with a class name — the name is not a utility: a typo, or a plain class of your own such as `card`. - **The same message plus "Are you using CSS modules or similar and missing `@reference`?"** — this compile has no theme at all, which is the separately compiled style block case. - **"… because the `x` variant does not exist"** — a variant in the list is unknown here: a typo, or a custom variant this compile cannot see. - **"You cannot use `@apply` inside `@keyframes`"** — move the declarations into the keyframe steps by hand. ## When it is the right tool 1. Styling HTML you cannot put utilities on — CMS output that can only carry `class="btn"`, or a third-party widget's generated markup. Keep that rule in `@layer components` so utilities still win. 2. A single small class shared by server-rendered templates that have no component system to hold the markup. 3. Keeping a one-off custom rule on the design tokens when a utility already expresses the value. In each case keep the rule in a layer and the list short, and prefer `var(--color-…)` when you need only one value: a variable reads the theme directly and copies nothing. In an interview, the strongest answer names both halves: what the directive mechanically does — copy, sort, nest variants — and the one or two situations where that copying is worth its cost.

  • In Tailwind CSS v4, can you `@apply` a class you wrote yourself, such as `.card` inside `@layer components`?
    No. `@apply` only resolves utilities Tailwind knows: built-in ones and ones registered with `@utility`. A plain `.card` rule is ordinary CSS in v4, so `@apply card` fails with `Cannot apply unknown utility class`. v3 allowed it because it treated `@layer components` classes as utilities; in v4 you register the class with `@utility` or apply its underlying utilities.
  • In Tailwind CSS v4, does `@import "tailwindcss" important;` make the declarations copied by `@apply` `!important`?
    No. The global flag marks the generated utilities `!important`, but since 4.1.12 `@apply` ignores that global state, so applied declarations come out without it. If one applied value genuinely must win, the class-level modifier — `@apply bg-red-700!` — says so explicitly.
  • In a Tailwind CSS v4 codebase, when is `@apply` the right tool despite its pitfalls?
    When you cannot put utilities on the element: CMS output that only carries `class="btn"`, or a third-party widget's generated markup. Write that rule in `@layer components` so utilities on the element can still override it, keep the list short, and use `var(--…)` instead when you need a single theme value.

  • @apply makes the element use the utility class itself at runtime
  • In v4 @apply can pull in any class, including your own component classes
  • The class listed last in @apply wins any conflict
  • @apply shrinks the CSS because the utilities are shared
  • Variants such as hover: cannot be used inside @apply

Assumes Tailwind CSS v4 (checked against 4.3.3); v4 limits @apply to built-in and @utility utilities, and 4.1.12 stopped @apply inheriting the global important flag.

open as a page

In Tailwind CSS v4, which cascade layers does `@import "tailwindcss"` set up, and where should your own base styles and component classes go?

level: middleimportance: must knowfreq 16%

basics

~20 s

Tailwind CSS v4 declares four native cascade layers in the order theme, base, components, utilities. Element defaults go in @layer base, on top of Preflight; reusable classes such as .btn go in @layer components, so a utility on the same element still overrides them.

open as a page

In Tailwind CSS v4, why does `@apply` fail inside a Vue or Svelte `<style>` block or a CSS Module, and what does `@reference` fix?

level: middleimportance: should knowfreq 12%

basics

~20 s

In Tailwind CSS v4, each component style block and CSS Module is compiled separately, without your main stylesheet's theme, custom utilities or custom variants. @reference loads those definitions for lookup without emitting any CSS; plain var(--color-…) references sidestep it for single values.

open as a page

After upgrading a project to Tailwind CSS v4, `md:btn` in markup generates nothing and `@apply btn` fails, though `.btn` still sits in `@layer components` — why, and what are your options?

level: seniorimportance: should knowfreq 6%

basics

~20 s

Tailwind CSS v3 turned classes inside @layer components into utilities, so variants and @apply worked on them. v4 emits native cascade layers and leaves that CSS as ordinary rules, so either register the class with @utility or move its states inside the rule.

open as a page

In Tailwind CSS v4, what do the `--spacing()` and `--alpha()` functions compile to in your own CSS, and why use them over hard-coded values?

level: middleimportance: nice to knowfreq 4%

basics

~20 s

In Tailwind CSS v4, --spacing(4) compiles to calc(var(--spacing) * 4) and --alpha(var(--color-x) / 50%) to color-mix(in oklab, var(--color-x) 50%, transparent). Both keep hand-written CSS on the theme's scale and palette, so changing a theme variable updates them too.

open as a page

In Tailwind CSS v4, how do you apply a variant such as `dark` or `hover` inside your own CSS rule, and what does it compile to?

level: middleimportance: nice to knowfreq 7%

basics

~20 s

In Tailwind CSS v4, @variant dark { … } inside a rule wraps that block in the variant's condition: by default dark becomes a prefers-color-scheme media query and hover becomes &:hover inside @media (hover: hover). Stacked and comma-separated lists arrived in 4.3.0.

open as a page