# Field

> Groups a label, a control, help text and an error, and wires their ids for assistive tech.

Category: Inputs · Atomic level: molecule · Built on Base UI Field
Page: https://ui.dtheo.dev/docs/components/field

## Install

```bash
npx dtheo@latest add field
# or, with the shadcn CLI
npx shadcn@latest add https://ui.dtheo.dev/r/field.json
```

Dependencies: @base-ui/react, clsx, tailwind-merge. Registry dependencies: utils, input.

## Exports

`Field`, `FieldLabel`, `FieldDescription`, `FieldError`, `FieldItem`, `Fieldset`, `FieldsetLegend`, `Label`

## Use it for

- Every form control that needs a label, a description or validation

## Reach for something else

- Checkboxes and switches with their own inline label: wrap them in a <label> instead
- Groups of related controls: use Fieldset with a legend

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `invalid` | `boolean` | – | Field: marks the control invalid and shows a matching FieldError. |
| `optional` | `boolean` | `false` | FieldLabel: adds a quiet "Optional" after the label. Required is the default. |
| `match` | `boolean \| ValidityState key` | – | FieldError: when to show the message; `true` shows it whenever the field is invalid. |

## Accessibility

- The label names the control; the description and error are announced with it.
- Errors say what happened and how to fix it ("Enter a gain between 0 and 10").
- Validate on blur or submit, not on every keystroke.

## Examples

### field-validation

```tsx
import * as React from 'react';
import { Field, FieldDescription, FieldError, FieldLabel } from '@/components/ui/field';
import { Input } from '@/components/ui/input';

const CURRENT_RUN = 'R-0412';

/** Return a message that says what is wrong and how to fix it, or null when the value is valid. */
function validateBaseline(value: unknown) {
  const run = String(value ?? '')
    .trim()
    .toUpperCase();
  // U+2011 (non-breaking hyphen) keeps the sample ID on one line when the message wraps.
  if (!run) return 'Enter the run to compare against, like R\u20110398.';
  if (!/^R-\d{4}$/.test(run))
    return `“${run}” is not a run ID. Use four digits after “R-”, like R\u20110398.`;
  if (run === CURRENT_RUN) return `${CURRENT_RUN} is the run under review. Pick an earlier run.`;
  return null;
}

export default function FieldValidation() {
  const actions = React.useRef<{ validate: () => void }>(null);
  // Validate the sample value once so the preview opens on the error; after that, validation runs on blur.
  React.useEffect(() => actions.current?.validate(), []);

  return (
    <Field
      className="w-full max-w-sm"
      validate={validateBaseline}
      validationMode="onBlur"
      actionsRef={actions}
    >
      <FieldLabel>Baseline run</FieldLabel>
      <Input defaultValue="R-398" autoComplete="off" spellCheck={false} />
      <FieldDescription>Overshoot and settling time are compared against this run.</FieldDescription>
      <FieldError />
    </Field>
  );
}
```

## Used in

- Run review (page): https://ui.dtheo.dev/examples/run-review
- Data table pattern (template): https://ui.dtheo.dev/docs/patterns/data-table
- Forms pattern (template): https://ui.dtheo.dev/docs/patterns/forms
