Tailwind Syntax State Modifiers

Tailwind CSS State Modifiers

This skill covers variants that target CSS states and pseudo-elements other than interaction states (hover, focus, active). Use it together with :

• tailwind-syntax-variants : full variant grammar including hover/focus, group/peer, attribute, and arbitrary variants
• tailwind-syntax-responsive : breakpoint and container-query variants
• tailwind-syntax-dark-mode : the dark: variant configuration

Quick Reference : Variant Categories

All variants in this skill are SHARED between v3 and v4 unless flagged otherwise. The one divergence : user-valid: and user-invalid: are v4-only (CSS-native, gated on browser support in v3).

Structural Variants : Position in Parent

<ul>
  <li class="first:pt-0">A</li>     <!-- &:first-child -->
  <li>B</li>
  <li>C</li>
  <li class="last:pb-0">D</li>      <!-- &:last-child -->
</ul>

<ul>
  <li class="odd:bg-gray-50 even:bg-white">A</li>   <!-- &:nth-child(odd/even) -->
  <li class="odd:bg-gray-50 even:bg-white">B</li>
</ul>

<ul>
  <li class="only:font-bold">Alone</li>             <!-- &:only-child -->
</ul>

<table>
  <tr class="first-of-type:font-bold last-of-type:border-b-0">
    <td>Row data</td>
  </tr>
</table>

<div class="empty:hidden"></div>                     <!-- &:empty (no children, no text) -->

Arbitrary nth- Selectors

NEVER apply structural variants to elements that share a parent with DIFFERENT element types unless you want the variant to count ALL siblings. first-of-type: counts only same-tag siblings ; first: counts every kind.

<!-- "first:" picks the heading even though it's not a li -->
<div>
  <h2 class="first:text-xl">Heading</h2>
  <ul>
    <li class="first:pt-0">First li (correct)</li>
    <li>Second</li>
  </ul>
</div>

Pseudo-Element Variants

The Content Utility (before / after)

Both v3 and v4 automatically insert content: '' for before: and after: WHEN PREFLIGHT IS ACTIVE. If Preflight is disabled, both versions fail silently : the pseudo-element does not render. This is the single most common before/after bug.

<!-- Works with preflight on (both v3 and v4) -->
<span class="before:ml-1 before:inline-block before:size-2 before:bg-red-500"></span>

<!-- Override the default with a string -->
<span class="before:content-['→'] before:mr-1">Next</span>

<!-- Read from data attribute -->
<span data-label="New" class="after:content-[attr(data-label)]"></span>

<!-- Empty content (also explicit) -->
<span class="before:content-['']"></span>

Source : https://tailwindcss.com/docs/hover-focus-and-other-states ("Tailwind will automatically add content: '' by default so you don't have to specify it unless you want a different value").

NEVER use a literal space between brackets in content-[...]. Whitespace is parsed as an underscore. Use content-['Hello_World'] (Tailwind converts _ to space) or content-["Hello World"] with double quotes.

Preflight-Disabled Workaround

When preflight: false (v3) or @import "tailwindcss/utilities"; only (v4 without the preflight import), you MUST add content-[''] explicitly to every before: / after: usage :

<!-- Preflight off : explicit content required -->
<span class="before:content-[''] before:ml-1 before:inline-block before:size-2 before:bg-red-500"></span>

Form State Variants

<input class="required:border-red-500" required />
<input class="optional:border-gray-300" />

<!-- HTML5 validation : :valid / :invalid match BEFORE first interaction -->
<input type="email" required
  class="invalid:border-red-500 invalid:text-red-700" />

<!-- v4 only : user-* variants match only AFTER user has interacted -->
<input type="email" required
  class="user-invalid:border-red-500 user-invalid:text-red-700" />

<input type="checkbox" class="checked:bg-blue-500" />
<input type="checkbox" class="indeterminate:bg-gray-400" />

<input type="radio" class="default:ring-2 default:ring-blue-500" />

<input type="text" disabled class="disabled:opacity-50 disabled:cursor-not-allowed" />
<input type="text" readonly class="read-only:bg-gray-50" />

<input class="placeholder-shown:border-gray-300" placeholder="Type here" />

<input type="text" class="autofill:bg-yellow-50" />

<input type="number" min="0" max="100"
  class="in-range:border-green-500 out-of-range:border-red-500" />

Variant Selectors

ALWAYS prefer user-invalid: over invalid: in v4 when styling field errors : invalid: fires on every required field as soon as the page loads, before the user has typed anything. user-invalid: waits for interaction. v3 has no user-* variants : work around with the :placeholder-shown trick or wire validation via JS.

<!-- v3 trick : invalid only matters after user typed something -->
<input type="email" required
  class="invalid:not-placeholder-shown:border-red-500"
  placeholder=" " />

Motion Preference Variants

<!-- Animation only when user has NOT set reduce-motion preference -->
<div class="motion-safe:animate-spin">spinner</div>

<!-- Static fallback when user prefers reduced motion -->
<div class="motion-safe:animate-bounce motion-reduce:opacity-50"></div>

ALWAYS gate animations with motion-safe: OR provide a motion-reduce: override. NEVER ship animate-spin unconditionally on critical UI : users with vestibular conditions can be physically hurt by it.

Target Variant : URL Fragment

<a href="#section-2">Jump</a>

<section id="section-2" class="target:bg-yellow-100">
  Section 2 (highlights when URL fragment is #section-2).
</section>

target: matches when the element's id equals the current URL fragment. Useful for in-page anchor highlighting without JS.

Open Variant : details / dialog / popover

<details class="open:bg-gray-50">
  <summary>Click to expand</summary>
  <p>Hidden until summary is clicked.</p>
</details>

<dialog id="d" class="backdrop:bg-black/30 open:p-4">
  <p>Modal content</p>
</dialog>

<div popover class="open:shadow-lg">popover content</div>

The v4 open: variant compiles to &:is([open], :popover-open, :open) so it matches <details>, <dialog>, and [popover] elements simultaneously. The v3 open: compiles to &[open] only and does NOT match popovers.

NEVER assume open: matches modals you open via dialog.showModal() : that adds the [open] attribute, which IS matched. Programmatically showing a <dialog> via .show() also sets [open].

Empty Variant

<div class="empty:hidden">
  <!-- if this div has zero children AND zero text, it is display:none -->
</div>

empty: matches both no-child and no-text states. Whitespace counts as text, so a <div> </div> is NOT empty. Use empty:hidden to collapse list placeholders that may receive no items.

Decision Tree : Which Variant Group?

Styling based on what?
├── Position among siblings → structural (first/last/nth-)
├── A pseudo-element (::before, ::placeholder, ::marker, etc.) → pseudo-element variants
├── A form input attribute state (required, disabled, checked) → form state
├── HTML5 validity (valid, invalid) → form-state, prefer user-valid/user-invalid in v4
├── User accessibility preference (reduced motion) → motion-safe/motion-reduce
├── URL fragment match → target:
├── details/dialog/popover open → open:
├── No children → empty:
└── User pointer interaction (hover, focus) → see tailwind-syntax-variants

Stacking With Other Variants

<!-- Position + hover -->
<li class="first:hover:bg-gray-100"></li>

<!-- Position + responsive -->
<li class="first:pt-0 md:first:pt-4"></li>

<!-- Form state + dark -->
<input class="invalid:border-red-500 dark:invalid:border-red-300" />

<!-- Pseudo-element + group -->
<div class="group">
  <span class="before:opacity-0 group-hover:before:opacity-100">→</span>
</div>

v4 stacks chains left-to-right (per upgrade guide). The functional intent is the same as v3 ; only the syntax order differs. See tailwind-syntax-variants for the stacking-order migration.

Reference Files

• references/methods.md : every variant with full CSS selector and browser-support note
• references/examples.md : full real-world patterns (validated form, drop-cap, custom bullet, modal backdrop, accessible spinner)
• references/anti-patterns.md : the empty-before-with-preflight-off trap, invalid: firing before user input, placeholder: on wrapper instead of input, first: counting wrong sibling type

Verified Sources

• https://tailwindcss.com/docs/hover-focus-and-other-states (v4)
• https://v3.tailwindcss.com/docs/hover-focus-and-other-states (v3)
• vooronderzoek-tailwind.md §6 Variant System