Tailwind CSS v4 Variants Not Working in "@layer components"

[iamaliybi]

Hi everyone,

I'm experiencing an issue with Tailwind CSS v4 where variants (such as hover, focus, etc.) are not being applied correctly when using @‌layer components.

Issue Description

1. When I define a class inside @layer components, it works as expected for base styles.
2. However, when I try to apply variants like hover: or focus:, they do not seem to work.

@layer components {
	.btn-success {
		display: flex;
		align-items: center;
		color: rgb(var(--c-white) / 1);
		border: 1px solid transparent;
		background-color: red;
		transition: opacity 250ms ease-in-out;
	}
}

Expected Behavior

The hover:btn-success class should have a red background color when hovered over.

Actual Behavior

The hover state does not get applied, and inspecting the generated CSS does not show the hover: styles.

Steps Tried:

1. Verified Tailwind is correctly installed and working.
2. Checked Tailwind v4 documentation but didn’t find anything addressing this specifically.
3. Also, it doesn't work when I try to use @layer utilities.

Questions:

Is this an expected behavior change in Tailwind v4?
Should variants be applied differently within @layer components?
Are there any workarounds or best practices for handling variants in @layer components?
Any insights or solutions would be greatly appreciated!

Thanks in advance!

[wongjn]

Is this an expected behavior change in Tailwind v4?

Yes, see https://tailwindcss.com/docs/upgrade-guide#adding-custom-utilities.

Should variants be applied differently within @layer components?
Are there any workarounds or best practices for handling variants in @layer components?

Variants don't get applied at all anymore. As per above, Tailwind v4 no longer does anything "special" for CSS inside @layers.

---

So, for equivalent in v4, you'd do:

@utility btn-success {
	@layer components {
		display: flex;
		align-items: center;
		color: rgb(var(--c-white) / 1);
		border: 1px solid transparent;
		background-color: red;
		transition: opacity 250ms ease-in-out;
	}
}

[iamaliybi]

Thank you very much, it's working. I have a question, what's the difference between utilities and components?

[wongjn]

As per the CSS:

tailwindcss/packages/tailwindcss/index.css

Line 1 in ff8fd8c

@layer theme, base, components, utilities;

components comes before utilities, so any non-!important declarations in components can be overridden by CSS in utilities.

[Inventoris]

@iamaliybi you can use the following entry:

@layer components {
	.btn-success {
		display: flex;
		align-items: center;
		color: rgb(var(--c-white) / 1);
		border: 1px solid transparent;
		background-color: red;
		transition: opacity 250ms ease-in-out;
                &:hover {
                  @media (hover: hover) {
                    background-color: var(--color-violet-700);
                  }
                }
	}
}

Here is the doc.

[iamaliybi]

Thank you, but I want to use it like hover:btn-success. Your answer works correctly, but when I define it as btn-success and hover over it...