In Tailwind CSS v4, what does the `@apply` directive do to your CSS rule, and when does reaching for it backfire?
answer
- copied, not referenced
- known utilities only
- variants become nested rules
- Tailwind's sort, not your list
- the rule's layer decides
basics
~20 sIn 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
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.
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.
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.
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.