form state variants

Form state variants — style inputs from their own pseudo-class

Every HTML form control carries state the browser already tracks: required, valid/invalid (via HTML5 constraint validation), checked, disabled, read-only, placeholder-shown, autofill, default. Tailwind v4 exposes each as a variant suffix that maps to the corresponding CSS pseudo-class. You style the state declaratively — no JS class toggling, no React useState, no Alpine store.

Two newer pseudo-classes also exist — :user-invalid / :user-valid — which only apply after the user has interacted with the field (so an untouched required field is not flagged red on first paint). Tailwind v4 exposes them as user-invalid: / user-valid:. They are the accessible choice over bare invalid:.

1 · live form validation demo — invalid: / valid: / checked:

Type in the email field. The border turns red while invalid (empty + required, or a malformed email) and green once a valid email is typed. Toggle the consent checkbox — the submit button only enables when the box is checked. Zero JavaScript drives the visual state — only the disabled toggle on the button uses JS, and that could also be done with peer-checked: (see group_peer).

Class breakdown — invalid:border-red-500 valid:border-green-500 swap border color based on the live HTML5 validity state. peer-checked:bg-cyan-500 on the button reads the checkbox (which carries class="peer") — that is the group_peer mechanism, layered on top of the form state. The enabled: variant is the inverse of disabled: — it matches only when the button is interactable.

2 · autofill: — overriding the browser's autofill chrome

When Chrome/Edge/Safari autofill an input, they paint a hardcoded background color (yellow in Chrome, blue in Safari) and a hardcoded text color — and plain background-color cannot override it. The only escape hatch is the non-standard :-webkit-autofill pseudo-class, which Tailwind v4 exposes as autofill:. You pair it with the box-shadow-inset hack to paint the field your way.

In Tailwind, you can apply this with arbitrary-value utilities under the autofill: variant. Browsers block programmatic autofill (you cannot trigger :-webkit-autofill from JS), so the mock below shows the visual before/after using static classes:

3 · placeholder-shown: — different style when empty

:placeholder-shown matches an input that is currently displaying its placeholder — i.e. it is empty. This lets you style the empty-vs-filled distinction without JS. Below: a dashed border when empty, a solid cyan border once the user types anything.

placeholder-shown: is NOT the same as the ::placeholder pseudo-element (which Tailwind exposes as placeholder:). The former targets the input element itself when empty; the latter targets only the placeholder text. They are easy to confuse.

HTML5 validation rules — what triggers :invalid

:invalid / :valid are powered by HTML5 constraint validation — the browser runs these checks on every input event. No JavaScript checkValidity() call needed.

Gotcha: an empty input WITHOUT required is always :valid (no constraint to violate). This is why the email demo above uses required — otherwise the empty field would already be green.

intent → pattern