Skip to main content

Label

The <label> element identifies the purpose of a form control. Styled via the classless element selector with a .label mirror class, and supports an automatic required-asterisk via CSS :has() plus an explicit .required class for cases the auto-mark cannot reach.

Usage​

When to use

  • Labeling every visible form control - text inputs, selects, checkboxes, radios, switches, ranges, file uploads, date and time pickers
  • As a group heading above a fieldset of radios or checkboxes when the group itself is required
  • Above a single checkbox where the inline checkbox text is the affirmation rather than the field name (e.g. "Terms and conditions" + "I accept")

When not to use

  • For decorative captions next to non-form content - use a heading or paragraph
  • As the only accessible name for a form control without for or wrapping - assistive tech needs the association

Do

  • Use for to bind the label to its control, or wrap the control inside the label
  • Add .required only when the auto-asterisk cannot reach the control (group headings, separated labels)
  • Keep label text short and meaningful - what the user is being asked for

Don't

  • Don't rely on placeholder text instead of a label
  • Don't add .required to inline checkbox or radio labels - the auto-mark intentionally exempts those
  • Don't restyle the label color or weight to indicate state - use the disabled and required attributes instead

API​

Slots​

SlotRequiredDescription
contentYesVisible label text.

Props​

PropTypeDefaultDescription
forstring-ID of the associated form control.
is_disabledboolean-Adds aria-disabled="true" to communicate the disabled state to assistive technology.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.subtleEmphasis-Lower emphasis; a muted, quieter weight.
.neutralEmphasisYesDefault emphasis; the standard weight at balanced contrast.
.accentEmphasis-Higher emphasis; a stronger, louder weight.
.xsSize-Extra small.
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.
.xlSize-Extra large.
.requiredAnnotation-Marks the field as mandatory.

Examples​

Before required input​

Label preceding a required <input>. The asterisk is auto-rendered via CSS :has() with no markup change.

After required checkbox​

Inline label following a required checkbox. The auto-mark is intentionally suppressed for inline checkbox text.

After required radio​

Inline label following a required radio. Auto-mark is suppressed for inline radio options.

Explicit required​

Standalone label with the .required class for cases where the label is not adjacent to its control.

Group header​

Group-level required label above a <fieldset> of radios.

Wrapping checkbox​

Consumer-authored <label><input type="checkbox"> Text</label>. The wrapping label renders as inline-flex with align-items: center, so the glyph and its accompanying text share a true vertical center. Inline font-weight, glyph gap, and pointer cursor cascade from the wrapped checkbox.

Wrapping radio​

Same pattern for radio groups - inputs share a name and any may be selected. Useful for legacy markup or quick prototypes where you don't want to mint a for/id pair.

Wrapping switch​

The switch is input[type="checkbox"][role="switch"]; the wrapping form sits next to its label like the other inline controls.

Wrapping disabled​

The disabled state propagates from the wrapped input to the label without any extra markup, matching the sibling form's auto-mirror.

Disabled​

Label rendered with aria-disabled="true" to mute its color and cursor.

Subtle​

The subtle emphasis, for a label that should sit quieter than the field it names.

Accent​

The accent emphasis, for a label that should stand out from the fields around it.

Controls​

Every shipped form control with its label, so the label treatment can be compared across the whole set at once.

Accessibility​

  • WCAG 2.2 AA
  • Native <label> semantics provide the programmatic association expected by every form control
  • Required state is announced via the required attribute on the control, not the visual asterisk - screen readers use the attribute
  • Disabled state uses aria-disabled="true" so the label is announced as disabled even though <label> itself does not accept the disabled attribute
  • form - vertical layout wrapper that hosts labels and their controls
  • fieldset - wraps groups of related controls under a <legend>
  • textfield, checkbox, radio, switch - controls that labels typically describe