Variant Reference

Every Tailwind v4 variant and the exact selector or at-rule it generates — pseudo-classes, form states, group and peer, responsive, container and media queries.

A variant is a prefix that wraps a utility in a condition. This page lists every built-in variant with the CSS it compiles to. & is the element the utility is on; … is the value you supply.

Pseudo-classes#

Structural#

Form states#

Relationship variants#

These style one element based on another element's state.

group-* and peer-* compose with any other variant: group-hover:, peer-checked:, group-has-checked:, peer-focus-visible:.

<!-- Ancestor state -->
<a href="#" class="group">
  <span class="text-gray-500 group-hover:text-indigo-600">Continue</span>
</a>

<!-- Earlier sibling state -->
<input type="email" class="peer" required />
<p class="hidden peer-user-invalid:block">Enter a valid email.</p>

<!-- Child state -->
<label class="border has-checked:border-indigo-500">
  <input type="radio" name="plan" />
</label>

not-*#

not-* inverts any other variant, including media and feature queries.

Pseudo-elements#

Responsive#

Breakpoints come from the --breakpoint-* namespace and are min-width by default.

Container queries#

Mark an ancestor @container, then query that ancestor's width instead of the viewport. Sizes come from the --container-* namespace.

Named containers disambiguate nesting:

<div class="@container/card">
  <div class="@container/media">
    <p class="@lg/card:text-lg">Sized against the card, not the media block.</p>
  </div>
</div>

Media & preference#

Feature queries#

<div class="bg-white/90 supports-[backdrop-filter]:bg-white/60 supports-[backdrop-filter]:backdrop-blur-md">…</div>

A bare property name tests for its existence: supports-[container-type]:. A full declaration tests for a value: supports-[display:grid]:. Use _ for spaces.

Attribute variants#

<button aria-expanded="false" class="aria-expanded:rotate-180">…</button>
<div data-state="open" class="hidden data-[state=open]:block">…</div>

starting#

v4

starting: supplies the value an element animates from the first time it is rendered — including elements moving out of display: none.

<div popover class="opacity-100 transition-discrete transition-opacity starting:open:opacity-0">
  Fades in on first paint.
</div>

Stacking variants#

Variants stack by chaining them with :. They read left to right as conditions, all of which must hold.

<button class="dark:md:hover:bg-fuchsia-600">…</button>

That is: in dark mode, at md and above, on hover.

<div class="p-6">
  <ul class="mx-auto max-w-xs divide-y divide-gray-200 rounded-lg border border-gray-200">
    <li class="px-4 py-2 text-sm first:rounded-t-lg last:rounded-b-lg odd:bg-gray-50 hover:bg-indigo-50">Alpha</li>
    <li class="px-4 py-2 text-sm first:rounded-t-lg last:rounded-b-lg odd:bg-gray-50 hover:bg-indigo-50">Beta</li>
    <li class="px-4 py-2 text-sm first:rounded-t-lg last:rounded-b-lg odd:bg-gray-50 hover:bg-indigo-50">Gamma</li>
  </ul>
</div>

Rules worth knowing:

• Order does not change the output for independent conditions. md:hover: and hover:md: generate the same rule. Pick one order and keep it consistent — the docs order is media query, then state.
• **Order does matter for group-*, peer-* and not-*, because they change what the rest of the selector attaches to. group-hover:focus: means "the group is hovered and** this element is focused".
• Tailwind sorts the output, not your class attribute. Utilities are emitted in a fixed cascade order, so text-sm md:text-lg works regardless of which you write first. Two utilities setting the same property at the same variant level resolve by that internal order, not by source order — do not rely on p-2 p-4.
• Stacked variants nest their at-rules. dark:md: produces a @media (prefers-color-scheme: dark) block containing a @media (width >= 48rem) block.
• Arbitrary variants stack too. [&_p]:hover:underline is valid; & marks the element and _ stands in for a space.

Arbitrary variants#

When no built-in variant fits, write the selector inline:

If the same arbitrary variant appears more than twice, promote it with @custom-variant.

Common mistakes#

• Putting peer after the element that reacts to it. Sibling combinators only look forward.
• Using invalid: for validation feedback. Use user-invalid: so untouched fields stay neutral.
• Expecting group-hover: to work without group. The marker class must be on an ancestor.
• Forgetting transition on the base state. Variants change the value; only transition makes the change animate.
• Overriding a *: rule on the child. Same specificity, later in the output — the parent wins.
• Removing focus styles with outline-none. Use outline-hidden, and add a focus-visible: ring.

Related topics#

• States & Variants — the same material with worked examples
• Custom Variants — @custom-variant and @variant
• Responsive Design — breakpoints in practice
• Container Queries — @container in depth
• Cheat Sheet — the utilities these variants wrap