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
foror wrapping - assistive tech needs the association
Do
- Use
forto bind the label to its control, or wrap the control inside the label - Add
.requiredonly 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
.requiredto 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
| Slot | Required | Description |
|---|---|---|
content | Yes | Visible label text. |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
for | string | - | ID of the associated form control. |
is_disabled | boolean | - | Adds aria-disabled="true" to communicate the disabled state to assistive technology. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.subtle | Emphasis | - | Lower emphasis; a muted, quieter weight. |
.neutral | Emphasis | Yes | Default emphasis; the standard weight at balanced contrast. |
.accent | Emphasis | - | Higher emphasis; a stronger, louder weight. |
.xs | Size | - | Extra small. |
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
.xl | Size | - | Extra large. |
.required | Annotation | - | 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
requiredattribute 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 thedisabledattribute