Label

Form field label with required, disabled, and tooltip affordances.

Status: stable. Group: form. Markdown version: /design-system/components/label.md

When to use

Label is the visible name of a form control. It requires htmlFor and renders a native label element, so click-to-focus and screen-reader name resolution are the browser's. required adds a visible asterisk (aria-hidden) plus screen-reader-only text (the translated "(required)", or requiredText), disabled applies the muted treatment, and tooltipText maps to the native title attribute.

When not to use

Do not place validation errors inside Label. Errors belong to the input's described-by region, not the label.
Do not use a Label as a section heading. Headings carry navigation semantics that Label does not.
Do not use Label as a heading above multiple controls; use FormField's group mode or a fieldset legend.

Look-alikes

FormField: Do not use Label as a heading above multiple controls; use FormField's group mode or a fieldset legend.
GroupLabel: Do not use as the label of an ordinary single input; that is Label. as="label" is for the primary control of a composite group.
Text: Do not label form fields with Text; use Label (htmlFor) and HelperText (aria-describedby).

Props

Label props
Prop	Type	Default	Description	Required
`htmlFor`	`string`	none	Id of the form control this label describes.	Yes
`tooltipText`	`string`	none	Native tooltip text; used as a fallback when `title` is not set.	No
`required`	`boolean`	`false`	Appends a "*" marker plus an sr-only hint, `requiredText` or the translated "(required)". It only changes the label text; the control still needs its own required.	No
`requiredText`	`string`	none	Screen-reader hint read after a required label. Defaults to the translated "(required)" (`label.required`).	No
`disabled`	`boolean`	`false`	Dims the label and shows a not-allowed cursor.	No
`variant`	`"option" \| "field"`	`field`	`field` names a control above or beside it (semibold); `option` is the text of a checkbox, radio or switch, which reads as plain text.	No

Variants

Available variants: field, option (default field).

Invalid combinations

The contract records no invalid combinations.

Keyboard

The contract records no keyboard interaction.

Rules

Every item under When not to use is a MUST NOT. MUST and SHOULD follow RFC 2119.

Label rules
Level	Rule	How it is checked
MUST	ARIA: HtmlFor associates control.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Required appends an aria-hidden asterisk and sr-only hint to the label's name: requiredText, or the translated "(required)" (`label.required`, "(pakollinen)" in FI, "(obligatoriskt)" in SV). The required state itself comes from the control's own required or aria-required.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	Required stories produce no axe violations at the configured severity.	Automated by `npm run test:stories:matrix:ci`. WCAG 2.5.8.
MUST	The accessibility tree (role, name, state) matches the committed snapshot for every required story.	Automated by `npm run test:stories:matrix:ci`. WCAG 1.3.1, 4.1.2.
MUST	The component remains legible and operable under a real browser forced-colors: active pass.	Automated by `npm run test:stories:hc`.
MUST	A human completed an end-to-end accessibility review of this component.	Manual review, last on 2026-11-04.
SHOULD	Always pass htmlFor with the input's id; the explicit association is grep-able and survives markup reordering.	Not stated in the contract.
SHOULD	Pair required on the Label with required on the input so the visual and ARIA states agree.	Not stated in the contract.
SHOULD	Pair disabled on the Label with disabled on the input; the prop is visual only and does not propagate.	Not stated in the contract.
SHOULD	Keep critical guidance in HelperText; native title tooltips do not fire on touch.	Not stated in the contract.
SHOULD NOT	Do not put validation errors in the Label; errors belong to the input's error state and the form-level error region.	Not stated in the contract.

Install and import

Install: npm install @digitaltableteur/react (version 0.9.1, restricted access on npm).
Import: import { Label } from "@digitaltableteur/react";
Entry point: @digitaltableteur/react/forms exports it too.
Styles: import @digitaltableteur/react/style.css once at the app boundary.
Also available as the custom element <dt-label>; see the custom elements manifest.