FormField

A Label + HelperText + ErrorText composition wrapper for a single form control.

Overview

FormField composes a Label + HelperText + ErrorText around a single form control, auto-wiring aria-describedby/aria-invalid where the platform allows it. It’s the foundation for the upcoming M12 form-patterns milestone — reach for it whenever a control needs a label, a helper message, or an error, instead of hand-rolling the id/ARIA wiring per screen.

On React, don’t also pass label/error directly to a wrapped Input/Textarea — FormField owns rendering those; the wrapped control reads its id and ARIA attributes from context instead.

Anatomy

No sketchy box — FormField is pure layout and typography. It renders (in order): an optional label, the wrapped control (via children on React/React Native, or a <slot> on Web Components), an optional helper-text line, and an optional error line. If both helperText and error are supplied, both render simultaneously — there is no hide-on-error switching.

Variants & States

Usage

Accessibility

This is the single most important section — the wiring mechanism is genuinely different on each platform:

• React: FormField provides { id, describedByIds, invalid } via context. Input and Textarea read it when present, computing their own id/aria-invalid/aria-describedby from it — but the wrapped control’s own label/error still render if FormField didn’t supply one, so passing both never silently loses a field’s label or error. Checkbox/Radio/Switch/Select/ Slider don’t consume this context yet — they have no error concept of their own, so wrapping them renders the label/helper/error text but wires nothing into them (a separate, larger future undertaking once those components gain their own error concept).
• Web Components: <gh-form-field> auto-wires id/aria-describedby/aria-invalid directly onto its slotted control — a string-form aria-describedby can’t reference elements inside gh-form-field’s own shadow root from a light-DOM sibling (ID references never cross a shadow boundary), so it reaches into its own light-DOM child and sets the attributes on it imperatively instead (ordinary, unrestricted DOM access from the host’s own script — only style encapsulation and slot projection are shadow-scoped). Re-syncs on slotchange too, if the wrapped control is swapped out after mount.
• React Native: no id/aria-describedby equivalent exists on this platform at all. FormField is a visual composition only — there is no automatic accessibility linkage between the helper/error text and the wrapped control. A screen-reader user focusing the control will not automatically hear the helper/error text. This is a real, permanent platform gap, not something faked via accessibilityHint cloning.
• See the Accessibility Guide for general conventions.

Content

The label names the value being collected (“Email”), not an instruction. Helper text explains a format or constraint before the user makes a mistake (“Letters, numbers, and underscores only”); error text explains what went wrong and how to fix it, after validation.

Props API

Code examples

// React — @ghds/react (wraps one control; label/error render on FormField)
import { FormField } from '@ghds/react/form-field';
import { Input } from '@ghds/react/input';

<FormField label="Password" error="Must be at least 8 characters">
  <Input type="password" />
</FormField>;

<!-- Web Components — @ghds/web-components (auto-wires id/aria onto the slotted control) -->
<script type="module">
  import '@ghds/web-components/form-field';
</script>
<gh-form-field for="password" label="Password" error="Must be at least 8 characters">
  <input type="password" />
</gh-form-field>

// React Native — @ghds/react-native (visual composition only; no ARIA linkage on this platform)
import { FormField } from '@ghds/react-native/form-field';
import { Input } from '@ghds/react-native/input';

<FormField label="Email" error={emailError}>
  <Input value={email} onChangeText={setEmail} />
</FormField>;

Live Demo

React and Web Components render live below. React Native can’t run in a browser without additional react-native-web wiring (not set up in this site), so its usage is shown as a code sample instead.