Skip to main content
Digitaltableteur

Design system components

GroupLabel

The group heading for sets of controls. With as="legend" as the first child of a <fieldset> it names the group, which is how FormField (and so CheckboxGroup), RadioGroup and the SelectableCard group render it; the default as="label" names one control through htmlFor.

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

When to use

GroupLabel is the one look for every group heading. Rendered as a legend inside a fieldset it names the whole group, and FormField, RadioGroup and the SelectableCard group already render it that way. Rendered as a label (the default) it points at one control through htmlFor, for the primary control of a composite input. For ordinary groups of same-name controls, use FormField or RadioGroup rather than wiring the fieldset yourself.

When not to use

  • 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.
  • Do not style as a heading; screen readers will navigate to it as a heading and miss the group it labels.

Look-alikes

  • FormField: Do not name a radio or checkbox set with as="label"; a label names one control. Use as="legend" inside a fieldset, or FormField.
  • Label: 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.

Props

GroupLabel props
PropTypeDefaultDescriptionRequired
as"label" | "legend"labelElement to render. legend (first child of a fieldset) names a group of controls; label names one control through htmlFor.No
htmlForstringnoneID of the control the label names. Required for label; ignored for legend.No
tooltipTextstringnoneOptional browser tooltip; fallback when title is not set.No
requiredbooleanfalseShows the required asterisk.No
disabledbooleanfalseMuted disabled styling.No
titlestringnoneNative title attribute override.No

Variants

  • Allowed as values: label, legend (default label).

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.

GroupLabel rules
LevelRuleHow it is checked
MUSTARIA: As="legend" as the first child of a <fieldset> gives the group its accessible name; a <label> inside a fieldset does not name the fieldset.Not yet verified: no evidence record. WCAG 4.1.2.
MUSTARIA: As="label" (the default) names one control through htmlFor.Not yet verified: no evidence record. WCAG 4.1.2.
MUSTARIA: The required asterisk is aria-hidden; the controls must expose the required state themselves.Not yet verified: no evidence record. WCAG 4.1.2.
MUSTRequired stories produce no axe violations at the configured severity.Automated by npm run test:stories:matrix:ci. WCAG 2.5.8.
MUSTThe 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.
MUSTThe component remains legible and operable under a real browser forced-colors: active pass.Automated by npm run test:stories:hc.
MUSTA human completed an end-to-end accessibility review of this component.Manual review, last on 2026-11-04.
SHOULDWith as="label", point htmlFor at the control that should receive focus when the text is clicked.Not stated in the contract.
SHOULDRender as="legend" as the first child of a fieldset to name a group of controls.Not stated in the contract.
SHOULDPair with required to show the asterisk when the underlying group must be filled; the asterisk is aria-hidden, so the controls carry the required state.Not stated in the contract.
SHOULDKeep the text a noun phrase (Delivery address), matching Label's tone.Not stated in the contract.
SHOULD NOTDo not name a radio or checkbox set with as="label"; a label names one control. Use as="legend" inside a fieldset, or FormField.Not stated in the contract.
SHOULD NOTDo not nest interactive elements inside it; as a label it forwards clicks to the target control.Not stated in the contract.

Install and import

  • Install: npm install @digitaltableteur/react (version 0.9.1, restricted access on npm).
  • Import: import { GroupLabel } 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-group-label>; see the custom elements manifest.

Links