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
| Guidance | Practice |
|---|---|
| Do | Pass form.fields.<name>.feedback from useForm to Field.Feedback, and set invalid when its type is error. |
| Do | Pass disabled={form.isSubmitting} with focusableWhenDisabled on text fields, so focus stays put while the form submits. |
| Do | Use Field.Label visuallyHidden when the design has no visible label. |
| Don’t | Pass render to Field.Label that is not a label. It warns in development. |
| Don’t | Set 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
| Prop | Type | Description |
|---|---|---|
orientation | FieldOrientation | horizontal puts the control beside a Field.Content that stacks the label and text.Default: 'vertical' |
disabled | boolean | Disables the control.Default: false |
focusableWhenDisabled | boolean | Keeps a disabled text control focusable: read-only and aria-disabled instead of disabled.Default: false |
required | boolean | Marks the control required.Default: false |
invalid | boolean | Marks 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
| Prop | Type | Description |
|---|---|---|
visuallyHidden | boolean | Hides 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
| Prop | Type | Description |
|---|---|---|
feedback | FormFieldFeedback | The 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
<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
<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>