HelperText

Helper or validation copy below form controls. Only the error state carries semantics (role=alert); warning, success and info differ by colour and an icon with no text alternative.

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

When to use

HelperText is the supporting line under a form control: a neutral hint, or a semantic error, warning, success, or info message with an auto-resolved icon. The system's inputs render it automatically via their helperText and error props; reach for it directly only when composing a custom field.

When not to use

Do not render multiple state="error" HelperTexts under one field; multiple live regions create overlapping announcements. Consolidate.
Do not use HelperText for page-level messages. AlertBanner and Toast exist for that scope.

Look-alikes

Text: Do not label form fields with Text; use Label (htmlFor) and HelperText (aria-describedby).

Props

HelperText props
Prop	Type	Default	Description	Required
`children`	`React.ReactNode`	none	The helper text content to display.	Yes
`id`	`string`	none	Optional ID for aria-describedby association.	No
`className`	`string`	none	Additional CSS class name.	No
`state`	`"info" \| "success" \| "warning" \| "error"`	none	Semantic state of the helper text (error, warning, success, info). Warning, success and info icons carry a translated text alternative, so the state is not conveyed by colour alone. Default is neutral/no state.	No

Variants

Allowed state values: info, success, warning, error.

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.

HelperText rules
Level	Rule	How it is checked
MUST	ARIA: Link to control via id / aria-describedby.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Warning, success and info prefix the copy with a visually hidden, translated state word ("Warning:", "Success:", "Info:"; `helperText.state.*`), so the state is not conveyed by colour and icon alone (WCAG 1.3.1, 1.4.1)	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Error renders role=alert and no state word: error copy states the problem itself.	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	Prefer the built-in helperText and error props on TextInput, TextArea, Select, Checkbox, and Switch; they render HelperText and wire aria-describedby for you.	Not stated in the contract.
SHOULD	Pass an id and reference it from the control's aria-describedby when composing manually, so the hint is announced with the field.	Not stated in the contract.
SHOULD	Keep it to one short sentence; longer guidance belongs in surrounding copy, not under the field.	Not stated in the contract.
SHOULD	Use state=error for validation failures; the paragraph becomes role=alert and announces immediately. The warning, success and info states add no semantics, so their copy must state the meaning in words.	Not stated in the contract.
SHOULD NOT	Do not put validation errors inside the Label; errors belong below the field, the label carries the field name.	Not stated in the contract.
SHOULD NOT	Do not hide the hint while an error shows; render the error HelperText above the hint and keep both visible, as FieldShell does for every system field.	Not stated in the contract.

Install and import

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