State Variants

So far every class has applied all the time. A variant is a prefix that makes a class apply only in certain circumstances: hover:bg-blue-700 is "the blue-700 background, but only while the pointer is over it". Variants are how Tailwind does everything that plain CSS does with :hover, :focus, :checked, :nth-child(), ::before and attribute selectors, without leaving your HTML. This chapter covers the state-based ones. Responsive and dark-mode variants, which work the same way, are chapters 7 and 8.

How a Variant Works

A variant puts a colon between a condition and a utility. The utility is unchanged; Tailwind wraps the same declaration in a selector for the condition:

The class name itself is escaped in the CSS (hover\:bg-blue-700), and the rule only matches in the state. Note the @media (hover: hover) around the hover rule: in v4 hover: applies only on devices whose main input can really hover. On a touch screen it is skipped, so a tap does not leave a button stuck in its hover style. (The headless Chrome I tested with reported matchMedia('(hover: hover)').matches as true.) The upgrade guide says that if you built a site that depended on hover firing on tap, you can restore the old behaviour with @custom-variant hover (&:hover);, but it recommends treating hover as an enhancement and never relying on it.

The Interaction and Form States

Each of these is a pseudo-class with the same name, taken from the generated CSS:

I tested several with real state. disabled:bg-gray-400 on a button with the disabled attribute gave the grey, and the enabled twin stayed blue. An email input holding nope with invalid:border-red-500 had a red border, and after I changed its value to a@b.co the border went back to grey. A <details open:bg-blue-100> was grey until I clicked its summary, and then blue (open became true).

Focus: focus, focus-visible and focus-within

Focus is the one to get right, because it is how keyboard users see where they are. The two variants differ, and I measured the difference. A button with focus:text-yellow-300 focus-visible:text-red-500, and a text input with the same classes:

A mouse click gives a button focus but not :focus-visible, because a person who just clicked it does not need an indicator; keyboard users do. So the pattern for buttons and links is to style focus-visible:: a ring or outline for keyboard users, nothing extra after a click. Text inputs always match :focus-visible (you are about to type), so either variant works on them. I measured a button with focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-600: after a mouse click its outline style was none; after Tab it was 2px solid with a 2px offset in blue. Never remove the outline without such a replacement (chapter 3).

focus-within: styles a container when something inside it has focus: a wrapper with border-gray-300 focus-within:border-blue-500 around an input was grey, and turned blue as soon as I clicked into the input. It is how you give a fancy input (an icon, a prefix) a focus state on the outer box.

Group and Peer: Styling One Thing from Another's State

A plain variant looks at the element's own state. Often you want to style one element based on the state of another, and Tailwind has two markers for that.

group marks a parent; group-hover:, group-focus: and so on style its descendants:

The selector reads "this element, when it is inside a .group that is hovered". When groups nest, a bare group is ambiguous (the nearest one? all of them?), so you name them, group/card and group/row, and write group-hover/card:. In the measurement the card-hover span lit up for the whole card, while the row-hover span lit up only when the pointer was inside the row (and, because the row is inside the card, hovering the row also counted as hovering the card).

peer marks an element so that its later siblings can style themselves from its state: peer-checked:, peer-invalid:, peer-focus-visible:. The generated selector uses the sibling combinator: .peer-checked\:bg-red-500:is(:where(.peer):checked ~ *). The ~ is the catch: the peer must come before the element that reacts to it. I built both orders and clicked both labels:

Both checkboxes were checked; only the label that came after its peer reacted. This is the whole trick behind CSS-only toggles, tabs and accordions (Exercise 2). The group version has the same limit in the other direction: group-* can only style descendants, not ancestors or earlier siblings.

aria-* and data-*: Styling from Attributes

Many components expose their state as attributes: aria-expanded="true" on a menu button, data-state="open" on a dialog (headless component libraries do this). Tailwind turns those attributes into variants, so no JavaScript has to add and remove classes:

The built-in aria- variants (I compiled aria-checked and aria-expanded; the official docs list more of the same kind) match the attribute set to "true"; for another value use brackets, as in aria-[sort=ascending]: ([aria-sort="ascending"]). data-active: matches the bare attribute being present, and data-[state=open]: matches a specific value. When several apply, the one that comes last in Tailwind's generated CSS wins, which is why the red one showed at the end.

Structural Variants: Position Among Siblings

Four list items with odd:bg-gray-100 even:bg-white first:rounded-t-lg last:rounded-b-lg measured: backgrounds gray-100, white, gray-100, white; the first item with an 8px radius at its top corners and the last with 8px at its bottom corners, and 0px elsewhere. This is zebra striping and rounded ends without a wrapper or extra classes.

Two variants style the children from the parent, so you do not repeat a class on every child: *: targets direct children (:is(.\*\:p-2 > *)) and **: targets all descendants. A <ul class="*:p-2"> gave each of its two items 8px of padding. A trade-off: the parent's rule is a more specific selector than the child's own class. With class="*:first:pt-0" on the list and pt-3 on each item, the first item measured 0px and the second 12px: the parent's variant overrode the child's own pt-3 where it applied.

has-*, not-* and in-*

has-* styles an element based on what it contains, which was impossible in CSS before :has(): has-checked:bg-blue-100 compiles to :has(:checked), and any selector goes in brackets, has-[:checked]: or has-[img]:. I made a <label class="has-checked:bg-blue-100"> around a checkbox: it had no background, and after I clicked the checkbox the whole label became blue-100. The same works from a group: group-has-[a]:block (compiled to :is(:where(.group):has(:is(a)) *)).

not-* is the negation: not-first:mt-2 is :not(:first-child), the classic "space between items but not before the first". For states it composes: not-hover:opacity-50 generated two rules, :not(:hover) and @media not (hover: hover), so the dimmed style applies on touch screens too. Measured: 0.5 at rest, 1 while hovered.

in-* is like group-* without the group marker: in-hover:opacity-100 compiles to :where(:hover) .in-hover\:opacity-100, "inside any hovered element". That "any" bites. Every page's <html> element is :hover while the pointer is anywhere over the page, so I measured an element with opacity-50 in-hover:opacity-100: 0.5 with the pointer outside the window, 1 with the pointer over an unrelated button (html:hover was true). For "this parent is hovered", use a named group. Treat in-hover: with suspicion; I did not test the other in-* variants, so check any you use against the same trap (does some ancestor, up to <html>, always match?).

Pseudo-elements

Variants also reach into the parts of an element that are not elements: before: and after: (::before, ::after), placeholder: (::placeholder), file: (::file-selector-button, the "Choose file" button), marker: (list bullets and numbers, applied to the element and its children), selection: (selected text), first-line:, first-letter: and backdrop: (a dialog's backdrop). For ::before and ::after you must give the pseudo-element some content, with the content-* class:

The second line is a v4 convenience: the before: and after: variants add content: var(--tw-content) themselves and --tw-content defaults to an empty string, so after:block after:size-4 already creates a box (the measured content was ""). You only write content-['…'] when you want actual text. A placeholder:text-red-500 input measured the red on its placeholder colour.

The ! Modifier and Variant Order

To make one utility win over everything, put ! at the end of the class: bg-red-500! compiles to background-color: var(--color-red-500) !important, and with a variant, hover:bg-red-600/50!. In v3 the ! went at the start; the upgrade guide says the old position still works but is deprecated. Reach for it rarely: needing it usually means two rules are fighting that should not be.

Hands-On Exercises