# Field

Labelling and validation for a single form control — label, description, and error message.

- Category: Forms
- Page: https://wunderui.com/components/field
- Tier: Free

## Install

```bash
npx wunderui-cli add field
```

## Import

```tsx
import { Field, FieldControl, FieldDescription, FieldError, FieldLabel } from "@/components/ui/field"
```

## Minimal usage

Then use it:

```tsx
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field"
import { Input } from "@/components/ui/input"

export function Email() {
  return (
    <Field>
      <FieldLabel>Work email</FieldLabel>
      <Input type="email" placeholder="name@company.com" />
      <FieldDescription>We send receipts to this address.</FieldDescription>
    </Field>
  )
}
```

Expected result: You see the label Work email above a white field with a grey placeholder, and the hint below it. A click on the label focuses the field, and the border turns indigo.

## Usage

```tsx
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field"
import { Input } from "@/components/ui/input"

export function Example() {
  return (
    <Field>
      <FieldLabel>Work email</FieldLabel>
      <Input type="email" placeholder="name@company.com" />
      <FieldDescription>We send receipts to this address.</FieldDescription>
    </Field>
  )
}
```

## When to use

### Use Field for

- A control that needs a label, a hint or an error message
- A form where the state (invalid, disabled) must reach the label and the messages
- A control that is not an Input, such as a Textarea, that should join a label and a hint

### Use something else

- [Fieldset](https://wunderui.com/components/fieldset) for a group of related controls that share one legend, such as an address or a set of checkboxes
- [Textarea](https://wunderui.com/components/textarea) for a Textarea that brings its own label, helper line and error
- [Checkbox](https://wunderui.com/components/checkbox) for one checkbox with its label and description in a single row
- [Form](https://wunderui.com/components/form) for the form that holds the Fields: submit, validation mode and server errors

## Behavior

What Field does itself, and what it leaves to the page.

- **Label wiring:** The label is linked to the control with generated ids, so you never write htmlFor. An Input inside an Input Group is still found, so the label points to the input and not the group.
- **Description and error wiring:** The description and error register with the Field, and the control gets them as its description. A screen reader reads the label, the control, then the hint, and the error while it shows.
- **Invalid:** Marking the Field invalid sets the invalid state on the Input, turns the border and focus ring red, and shows the error. The fill of the control stays white.
- **FieldError:** The error shows only while the field is invalid, unless a match setting shows it at once or for one rule. Without children it prints the failed check's message.
- **Disabled:** Disabled reaches the control, dims the label and hint to 40% and skips the control in the tab order. A Field inside a disabled Fieldset is disabled too.
- **Form:** Inside a Form, give the Field a name. Errors passed to the Form by that name make the Field invalid and stay until you pass new ones, so clear them after the next submit.
- **Read-only:** Read-only belongs to the control: set it on the Input. The control stays readable, focusable and copyable, and is filled with the subtle tone.
- **Motion:** The Field adds no motion of its own. The control fades its border colour on the fast duration, and messages appear without moving the controls around them when you keep a line of room.
- **Reduced motion:** Nothing moves, so there is nothing to reduce. The colour change of the control stays: it is a short fade, not movement.

## Anatomy

- `Field`: The wrapper of one control: a column with 4 px between its parts. It owns the name, invalid, disabled and validation state, and every part inside reads them.
- `FieldLabel`: The visible name of the control, in 14 px medium text with 4 px below it. It is linked to the control, so a click on it focuses the control, and it dims with a disabled field.
- `FieldControl`: The control itself. An Input joins the Field by itself, any other control such as a Textarea joins through FieldControl, and the Field passes it the invalid and described-by attributes.
- `FieldDescription`: The hint under the control in 12 px tertiary text. It is linked to the control, so a screen reader reads it after the label, and it dims with a disabled field.
- `FieldError`: The error message in 12 px error text. It shows only while the field is invalid, is linked to the control and is left out while the field is disabled, so hide the hint while it shows.

## Best practices

### When to use

- Use Field around every control with a label, hint or error. It draws no box; put Fields in a Fieldset for a group, and use Form to send data and take server errors.

### Do

- Put the label first, then the control, then the hint or the error. A label is a noun (Work email) and a hint is a full sentence.
- Give each Field a name when it sits in a Form. The name is how an error you pass to the Form finds its field.
- Write the error as an instruction: Enter an email address like name@company.com, not Invalid. Show it after the person leaves the field or sends the form, and keep what they typed.
- Render the hint only while there is no error, so the error takes its place. Keep a line of room for the message so the controls below do not jump.
- Mark an exception on the label row (Optional), not in the placeholder. A placeholder is gone once the person starts to type.

### Don't

- Don't build the label, hint and error by hand with label, p and ids. You lose the links that Field sets and the state that reaches every part.
- Don't put two controls in one Field. The label names one control; two controls need a Fieldset with a legend.
- Don't disable only the control and leave the Field enabled. The label and hint then stay at full strength next to a dimmed control.

## API reference

### Field

| Prop | Type | Default | Description |
|---|---|---|---|
| actionsRef | React.RefObject<FieldRoot.Actions \| null> |  | A ref to imperative actions. - `validate`: Validates the field when called. |
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| dirty | boolean |  | Whether the field's value has been changed from its initial value. Useful when the field state is controlled by an external library. |
| disabled | boolean | false | Disables the control, dims the label and the hint to 40 % and skips the control in the tab order. It also takes the place of `disabled` on the control. |
| invalid | boolean |  | Marks the field invalid. The control gets `aria-invalid`, the border and the ring turn red, and `FieldError` shows. Use it when you decide the state yourself; a Form's `errors` set it for you. |
| name | string |  | Identifies the field in a form. In a `Form` it is the key that the `errors` object uses to find this field, and the name of the value that `onFormSubmit` receives. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |
| touched | boolean |  | Whether the field has been touched. Useful when the field state is controlled by an external library. |
| validate | ((value: unknown, formValues: Form.Values) => string \| string[] \| null \| void \| Promise<string \| string[] \| null \| void>) |  | A function for a check of your own. It gets the value and the form values and returns a message (or an array of messages) when the value is wrong, and `null` when it is fine. |
| validationDebounceTime | number | 0 | How long to wait between `validate` callbacks if `validationMode="onChange"` is used. Specified in milliseconds. |
| validationMode | "onBlur" \| "onChange" \| "onSubmit" | 'onSubmit' | When `validate` runs: `onSubmit` (the default) checks on submit and again on every change after that, `onBlur` checks when the control loses focus, `onChange` checks on every change. It takes precedence over the same prop on the Form. |

Also accepts React.HTMLAttributes attributes.

### FieldControl

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| defaultValue | React.ComponentProps<'input'>['defaultValue'] |  | The value the control starts with when it keeps its own value. A plain `Input` takes `defaultValue` itself. |
| onValueChange | ((value: string, eventDetails: FieldControl.ChangeEventDetails) => void) |  | Callback fired when the `value` changes. Use when controlled. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.InputHTMLAttributes attributes.

### FieldDescription

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

### FieldError

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| match | boolean \| keyof ValidityState |  | When the error shows. `true` shows it at once, a validity key such as `valueMissing` or `typeMismatch` shows it for that rule only, and without it the error shows whenever the field is invalid. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

### FieldLabel

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| nativeLabel | boolean | true | Whether the label is a native `<label>` element. It is by default. Set it to `false` when you replace the element through `render` with something that is not a label, such as a `div`, so it does not inherit label behaviour. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.LabelHTMLAttributes attributes.

## Examples

### Layout: stacked and inline

```tsx
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field"
import { Input } from "@/components/ui/input"

export function Example() {
  return (
    <Field>
      <FieldLabel>Work email</FieldLabel>
      <Input type="email" placeholder="name@company.com" />
      <FieldDescription>We send receipts to this address.</FieldDescription>
    </Field>
  )
}
```

### Label and hint: label, hint, optional and link

```tsx
import { Field, FieldLabel } from "@/components/ui/field"
import { Input } from "@/components/ui/input"

export function Example() {
  return (
    <Field>
      <FieldLabel>Username</FieldLabel>
      <Input placeholder="nora.lindgren" />
    </Field>
  )
}
```

### Control: input, input group and textarea

```tsx
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field"
import { Input } from "@/components/ui/input"

export function Example() {
  // Input joins its Field by itself: the label, the hint and the error are linked to it, no ids needed.
  return (
    <Field>
      <FieldLabel>Work email</FieldLabel>
      <Input type="email" placeholder="name@company.com" />
      <FieldDescription>We send receipts to this address.</FieldDescription>
    </Field>
  )
}
```

### States: default, invalid, disabled and read-only

```tsx
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field"
import { Input } from "@/components/ui/input"

export function Example() {
  return (
    <Field>
      <FieldLabel>Work email</FieldLabel>
      <Input type="email" placeholder="name@company.com" />
      <FieldDescription>We send receipts to this address.</FieldDescription>
    </Field>
  )
}
```

## In context

### Invite a teammate: an error that appears on submit

Send the empty form, then daniel.okafor@wunderui.com, which is taken. The message replaces the hint and the border turns red, and both clear when the person types again.

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { Field, FieldControl, FieldDescription, FieldError, FieldLabel } from "@/components/ui/field"
import { Input } from "@/components/ui/input"
import { Textarea } from "@/components/ui/textarea"

const TAKEN = "daniel.okafor@wunderui.com"
const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/

export function Example() {
  const [email, setEmail] = useState("")
  const [error, setError] = useState("")
  const [sent, setSent] = useState("")

  return (
    <form
      className="flex flex-col gap-4"
      noValidate
      onSubmit={(event) => {
        event.preventDefault()
        const value = email.trim().toLowerCase()
        setSent("")
        if (!EMAIL.test(value)) setError("Enter an email address like name@company.com.")
        else if (value === TAKEN) setError("Daniel Okafor is already in this workspace.")
        else setSent(`Invitation sent to ${value}.`)
      }}
    >
      <Field name="email" invalid={error !== ""}>
        <FieldLabel>Email</FieldLabel>
        <Input
          type="email"
          placeholder="name@company.com"
          autoComplete="off"
          value={email}
          onChange={(event) => {
            setEmail(event.target.value)
            setError("")
          }}
        />
        {error ? <FieldError match>{error}</FieldError> : <FieldDescription>We send the invitation to this address.</FieldDescription>}
      </Field>
      <Field name="note">
        <FieldLabel>Note</FieldLabel>
        <FieldControl render={<Textarea placeholder="Add a line for the invitation" />} />
      </Field>
      <Button type="submit" variant="gradient">
        Send invitation
      </Button>
      <p aria-live="polite" className="min-h-5 text-sm text-text-secondary">
        {sent}
      </p>
    </form>
  )
}
```

### Workspace settings: label and hint beside the control

Inline rows line the labels up in one column. A read-only row keeps its value readable and copyable, and a narrow screen falls back to stacked.

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field"
import { Input } from "@/components/ui/input"

const ROW = "grid grid-cols-1 gap-x-6 gap-y-1 @lg:grid-cols-[11rem_1fr]"
const CONTROL = "@lg:col-start-2 @lg:row-span-2 @lg:row-start-1 @lg:self-center"

export function Example() {
  const [saved, setSaved] = useState(false)

  return (
    <form
      className="@container flex flex-col gap-5"
      onSubmit={(event) => {
        event.preventDefault()
        setSaved(true)
      }}
      onChange={() => setSaved(false)}
    >
      <Field className={ROW}>
        <FieldLabel className="@lg:col-start-1 @lg:row-start-1">Workspace name</FieldLabel>
        <Input defaultValue="WunderUI" className={CONTROL} />
        <FieldDescription className="@lg:col-start-1 @lg:row-start-2">Shown in the sidebar.</FieldDescription>
      </Field>
      <Field className={ROW}>
        <FieldLabel className="@lg:col-start-1 @lg:row-start-1">Billing email</FieldLabel>
        <Input type="email" defaultValue="info@wunderui.com" className={CONTROL} />
        <FieldDescription className="@lg:col-start-1 @lg:row-start-2">Invoices go here.</FieldDescription>
      </Field>
      <Field className={ROW}>
        <FieldLabel className="@lg:col-start-1 @lg:row-start-1">Workspace URL</FieldLabel>
        <Input readOnly defaultValue="wunderui.com/workspace" className={CONTROL} />
        <FieldDescription className="@lg:col-start-1 @lg:row-start-2">Set by your plan.</FieldDescription>
      </Field>
      <div className="flex items-center justify-end gap-2">
        <p aria-live="polite" className="mr-auto text-sm text-text-secondary">
          {saved ? "Settings saved." : ""}
        </p>
        <Button type="submit" variant="gradient">
          Save settings
        </Button>
      </div>
    </form>
  )
}
```

## For AI agents

`get_component("field")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
