docs / patterns / field-group

FieldGroup

a form field that keeps its label, control, description and error message together as one accessible unit. mount a FieldError and the control flips to invalid, with the message linked, on its own.

intensity · structuresrsc · client

provenance

authored in usva

layer

core / patterns

intensity

structures · organizes a region, stays out of the content

composition

one control per group: Input, Select, whatever FieldControl clonesrender FieldError conditionally, mounting it is the error stateFieldControl takes exactly one child elementnever two controls in one group, every derived id points at one thing

a11y

the label is wired via htmlFor · FieldError is role="alert" · description and error ids land in aria-describedbyjest-axe

dependencies

Label from the same package
live demo · try it outtype without an @ to trip the error

type without an @ to trip the error state.

A healthy field: description wired to aria-describedby, no error.

props

proptypedefaultnotes
idstring—base id for the field; derived ids power htmlFor and aria-describedby. auto-generated when omitted.
classNamestring—merged onto the root wrapper, a flex column.
...div propsHTMLAttributes<HTMLDivElement>—any standard div attribute is forwarded to the wrapper.

get it

bun add @usva-ui/reactcopy
usagecopy
import { FieldControl, FieldDescription, FieldError, FieldGroup, FieldLabel } from "@usva-ui/react/patterns/field-group";
import { Input } from "@usva-ui/react/primitives/input";

<FieldGroup>
  <FieldLabel>Email address</FieldLabel>
  <FieldControl>
    <Input type="email" placeholder="you@studio.fi" />
  </FieldControl>
  <FieldDescription>We only email about releases.</FieldDescription>
  <FieldError>Enter a valid email address.</FieldError>
</FieldGroup>