# 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

- 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 | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `FieldOrientation` | `'vertical'` | `horizontal` puts the control beside a `Field.Content` that stacks the label and text. |
| `disabled` | `boolean` | `false` | Disables the control. |
| `focusableWhenDisabled` | `boolean` | `false` | Keeps a disabled text control focusable: read-only and `aria-disabled` instead of `disabled`. |
| `required` | `boolean` | `false` | Marks the control required. |
| `invalid` | `boolean` | `false` | Marks the control `aria-invalid`. |

### 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 | Default | Description |
| --- | --- | --- | --- |
| `visuallyHidden` | `boolean` | `false` | Hides the label but keeps it in the accessibility tree. |

### 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 | Default | 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

```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>
```

## Related

- [useForm](/docs/hooks/use-form.md)
- [Input](/docs/components/input.md)
- [Checkbox](/docs/components/checkbox.md)
- [Form](/docs/primitives/form.md)
