Skip to content
Mosaic
On this page

Field

Wraps one form control with its label, description and feedback, and wires them together: the control takes the field's id, disabled, required, aria-invalid, aria-labelledby and aria-describedby.

Use for

  • a labelled input in a form
  • showing a field error, hint or success message under a control
  • a checkbox or radio beside its label and description

Practices

GuidancePractice
DoPass form.fields.<name>.feedback from useForm to Field.Feedback, and set invalid when its type is error.
DoPass disabled={form.isSubmitting} with focusableWhenDisabled on text fields, so focus stays put while the form submits.
DoUse Field.Label visuallyHidden when the design has no visible label.
Don’tPass render to Field.Label that is not a label. It warns in development.
Don’tSet id or aria-describedby on the control by hand. The field wires them.

API reference

Field.Root

Holds the field state for its parts and control. Carries data-orientation.

Slot: cl-field-root

PropTypeDescription
orientationFieldOrientationhorizontal puts the control beside a Field.Content that stacks the label and text.Default: 'vertical'
disabledbooleanDisables the control.Default: false
focusableWhenDisabledbooleanKeeps a disabled text control focusable: read-only and aria-disabled instead of disabled.Default: false
requiredbooleanMarks the control required.Default: false
invalidbooleanMarks the control aria-invalid.Default: false

Field.Header

A row with the label at the start and an action, such as a link, at the end.

Slot: cl-field-header

Field.Label

A native label for the control. For a control a label would activate, such as a select, renders a span that focuses it and names it through aria-labelledby. Carries data-visually-hidden.

Slot: cl-field-label

PropTypeDescription
visuallyHiddenbooleanHides the label but keeps it in the accessibility tree.Default: false

Field.Content

Stacks a horizontal field's label and supporting text.

Slot: cl-field-content

Field.Description

Supporting text, as a p. The control is described by it.

Slot: cl-field-description

Field.Message

A role="status" box that animates its height to the shown message and crossfades between Field.Error, Field.Hint and Field.Success.

Slot: cl-field-message

Field.Feedback

A Field.Message holding one error, hint or success, picked from feedback.

Slot: cl-field-message

PropTypeDescription
feedbackFormFieldFeedbackThe field feedback from useForm. warning and info show as a hint.

Field.Error

Error text with an icon. Shows while it has children, and the control is described by it.

Slot: cl-field-error

Field.Hint

Info text. Shows while it has children, and the control is described by it.

Slot: cl-field-info

Field.Success

Success text with a checkmark. Shows while it has children, and the control is described by it.

Slot: cl-field-success

Examples

A form field

TSX
<Field.Root
  required
  disabled={form.isSubmitting}
  focusableWhenDisabled
  invalid={feedback?.type === 'error'}
>
  <Field.Label>{m.emailLabel}</Field.Label>
  <Input type='email' {...form.register('emailAddress')} />
  <Field.Feedback feedback={feedback} />
</Field.Root>

A control beside its label

TSX
<Field.Root orientation='horizontal'>
  <Radio.Item value='all' />
  <Field.Content>
    <Field.Label>{m.all}</Field.Label>
    <Field.Description>{m.allDescription}</Field.Description>
  </Field.Content>
</Field.Root>