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?
answer
- what v3 did with @layer
- native layers, no interception
- ordinary CSS, not a utility
- a registered utility, or not
- who consumes the class
basics
~20 sTailwind 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.
solid answer
~50 sIn v3, Tailwind intercepted `@layer components` and `@layer utilities`: classes inside became utilities that took `hover:` or `md:` and could be `@apply`-ed. v4 emits real cascade layers and no longer hijacks `@layer`, so `.btn` is just a rule in the components layer — `md:btn` matches no utility and `@apply btn` fails with `Cannot apply unknown utility class`. One fix is `@utility btn { … }`, which the upgrade tool generates for these blocks: a real utility that takes variants and can be applied, sorted by property count so single-property utilities still override it. The other is to keep `.btn` a component class and put its states inside the rule with `@variant md { … }`, using plain `btn` in markup. A utility is only generated when the scanner sees the class, so a class used only by unscanned CMS HTML is safer kept as a component class.
code
css · 18 lines/* Option 1: a real utility — takes md:, works with @apply */
@utility btn {
border-radius: var(--radius-md);
padding-inline: --spacing(4);
padding-block: --spacing(2);
}
/* Option 2 (instead of option 1): a component class that owns its states */
@layer components {
.btn {
border-radius: var(--radius-md);
padding-inline: --spacing(4);
padding-block: --spacing(2);
@variant md {
padding-inline: --spacing(6);
}
}
}go deeper
Recall that in Tailwind v4 a class you write inside @layer components is plain CSS, not a utility, so prefixes such as md: do not work on it.
Explain how v3 treated @layer components classes as utilities, why v4's native layers ended that, and which error @apply raises for such a class.
Choose per class between @utility and a component class that owns its states, accounting for variant use, @apply consumers and content the scanner never sees, then verify utilities still override it.
Plan a v3 to v4 migration across many packages: inventory layered classes, decide which become utilities, and set a rule that a new shared class is either a utility or a component, never both.
## What v3 did with `@layer` In **Tailwind CSS v3**, `@layer base`, `@layer components` and `@layer utilities` were Tailwind's own constructs, processed at build time. A class written inside `@layer components` or `@layer utilities` was registered as if it were a utility: - it accepted variants — `hover:btn`, `md:btn`; - it could be pulled into another rule with `@apply btn`; - `@layer components` content was output before the utilities, so utilities still overrode it. ## What v4 does instead **Tailwind CSS v4** emits **native cascade layers** (`theme, base, components, utilities`) and, in the upgrade guide's words, no longer hijacks the `@layer` at-rule. Whatever you write inside `@layer components` is ordinary CSS that the browser places in that layer. The guide names `@utility` as the replacement for classes that should act like utilities. | Symptom after the upgrade | Cause in v4 | |---|---| | `md:btn` or `hover:btn` in markup generates nothing | no utility named `btn` exists; the scanner finds the token, but nothing matches it | | `@apply btn` fails with `Cannot apply unknown utility class` | `@apply` only resolves built-in utilities and `@utility` definitions | | plain `class="btn"` still works | the rule is ordinary CSS and is emitted as written | | `class="btn bg-red-700"` still turns red | `utilities` still comes after `components` | ## Option 1: register it with `@utility` ```css @utility btn { border-radius: var(--radius-md); padding-inline: --spacing(4); padding-block: --spacing(2); } ``` - It becomes a real utility: `md:btn` works and `@apply btn` works. - It moves into the `utilities` layer. v4 sorts custom utilities by how many properties they define, putting multi-property ones like `btn` before single-property utilities, so `bg-red-700` still overrides it. - The upgrade tool, `npx @tailwindcss/upgrade` (it needs Node.js 20 or higher), performs this conversion for `@layer utilities` and `@layer components` blocks when it migrates a v3 project. A manual upgrade leaves them as they were, which is one way this symptom appears. - The trade-off: like every utility, `btn` is generated **only when the scanner finds it** in your sources. If the class appears only in CMS-rendered HTML that Tailwind never scans, `@utility btn` produces no CSS until the scanner is told about that content. Writing more elaborate custom utilities is its own subject; here `@utility` is only the destination for the class. ## Option 2: keep it a component class - Leave `.btn` in `@layer components` and move its states inside the rule — nesting such as `&:hover`, or `@variant md { … }` so the class uses the project's own breakpoint. - Change markup from `md:btn` to plain `btn`; the responsive behaviour now lives in the class. - The rule is always emitted, so CMS output that only knows `btn` keeps working with no scanner configuration. - Rules that used `@apply btn` repeat the underlying utilities instead, or the markup carries both classes. ## Choosing, class by class 1. List every class inside `@layer components` and `@layer utilities`, then search templates and stylesheets for variant-prefixed uses (`md:btn`) and `@apply` of each. 2. A class only ever used plain, or consumed by content Tailwind does not scan, stays a component class. 3. A class used with variants or applied elsewhere, and visible in scanned templates, becomes `@utility`. 4. Recheck overrides afterwards: both options keep utilities winning, but any leftover rule moved outside a layer during the edit would beat them all. The underlying lesson is that `@layer` now means exactly what the CSS specification says and nothing more; any utility-like behaviour has to be asked for explicitly. ## Verifying the result - Build once and search the output for each converted class: a `@utility` that no scanned file uses will be absent, which is expected only if nothing needs it. - Load a page that uses `md:btn` and check that the responsive rule appears in the utilities layer. - Load a CMS-rendered page and confirm every class it relies on is still styled. - Check one element that combines the class with an overriding utility, such as `btn bg-red-700`, and confirm the utility still wins.
- In Tailwind CSS v4, why does `@utility btn` with several declarations still lose to `bg-red-700` on the same element?Both live in the `utilities` layer, so stylesheet order decides. v4 sorts custom utilities by how many properties they define, placing multi-property ones like `btn` before single-property utilities, so `bg-red-700` comes later and wins without extra configuration.
- In Tailwind CSS v4, `btn` appears only in CMS-rendered HTML that Tailwind does not scan. Which option keeps it working without changing what the scanner reads?Keeping `.btn` as a plain rule in `@layer components`. Ordinary CSS is emitted as written, whereas a `@utility` is generated only when the scanner finds the class in your sources; with `@utility` you would also have to point the scanner at that content or safelist the class.
- What does Tailwind CSS v4's upgrade tool do with a v3 project's `@layer components` blocks?`npx @tailwindcss/upgrade`, which needs Node.js 20 or higher, rewrites the classes inside `@layer utilities` and `@layer components` into `@utility` definitions while migrating the project. Review the result: a class used only by unscanned content may be better kept as a component class.
- Classes inside @layer components still work with variants in v4
- v4 simply ignores @layer components blocks, so .btn stops rendering
- @utility makes btn win over every other utility on the element
- A @utility class is emitted even if no scanned file uses it
- Adding the class to a v3-style safelist restores md:btn
Assumes Tailwind CSS v4 (checked against 4.3.3); v4 stopped treating classes inside @layer components and @layer utilities as utilities; @utility replaces that behaviour.