---
title: Field
description: "`Field` is a component used to group form elements with label, helper message, error message, etc."
links:
  - source: https://github.com/yamada-ui/yamada-ui/tree/main/packages/react/src/components/field
  - storybook: https://yamada-ui.github.io/yamada-ui?path=/story/components-field--basic
---

```tsx
<Field.Root label="Email address">
  <Input type="email" placeholder="your email address" />
</Field.Root>
```

## Usage

```tsx
import { Field } from "@yamada-ui/react"
```

```tsx
import { Field } from "@/components/ui"
```

```tsx
import { Field } from "@workspaces/ui"
```

```tsx
<Field.Root>
  <Field.Label />
  <Field.HelperMessage />
  <Field.ErrorMessage />
</Field.Root>
```

### Displaying a Helper Message

To display a helper message, set a `ReactNode` to `helperMessage`.

```tsx
<Field.Root helperMessage="We'll never share your email." label="Email address">
  <Input type="email" placeholder="your email address" />
</Field.Root>
```

Alternatively, you can customize using `Field.HelperMessage`.

```tsx
<Field.Root label="Email address">
  <Input type="email" placeholder="your email address" />
  <Field.HelperMessage color="warning">
    We'll never share your email.
  </Field.HelperMessage>
</Field.Root>
```

### Displaying an Error Message

To display an error message, set `invalid` to `true` and assign a `ReactNode` to `errorMessage`.

```tsx
<Field.Root errorMessage="Email is required." invalid label="Email address">
  <Input type="email" placeholder="your email address" />
</Field.Root>
```

Alternatively, you can customize using `Field.ErrorMessage`.

```tsx
<Field.Root invalid label="Email address">
  <Input type="email" placeholder="your email address" />
  <Field.ErrorMessage color="success">Email is required.</Field.ErrorMessage>
</Field.Root>
```

### Replacing Helper and Error Messages

Error messages are only displayed when `invalid` is `true`. To replace the helper message with the error message when the error message is displayed, set `replace` to `true`.
By default, it is set to `true`.

```tsx
<VStack>
  <Field.Root
    errorMessage="Email is required."
    helperMessage="We'll never share your email."
    invalid
    label="Email address"
    replace
  >
    <Input type="email" placeholder="your email address" />
  </Field.Root>

  <Field.Root
    errorMessage="Email is required."
    helperMessage="We'll never share your email."
    invalid
    label="Email address"
    replace={false}
  >
    <Input type="email" placeholder="your email address" />
  </Field.Root>
</VStack>
```

### Required

To make it required, set `required` to `true`.

```tsx
<Field.Root
  helperMessage="We'll never share your email."
  label="Email address"
  required
>
  <Input type="email" placeholder="your email address" />
</Field.Root>
```

### Disable

To disable, set `disabled` to `true`.

```tsx
<Field.Root
  disabled
  helperMessage="We'll never share your email."
  label="Email address"
>
  <Input type="email" placeholder="your email address" />
</Field.Root>
```

### Read-Only

To make it read-only, set `readOnly` to `true`.

```tsx
<Field.Root
  helperMessage="We'll never share your email."
  label="Email address"
  readOnly
>
  <Input type="email" placeholder="your email address" />
</Field.Root>
```

### Change Direction

To change the direction, set `orientation` to `"horizontal"` or `"vertical"`. By default, `"vertical"` is set.

```tsx
<VStack>
  <For each={["vertical", "horizontal"]}>
    {(orientation, index) => (
      <Field.Root
        key={index}
        helperMessage="We'll never share your email."
        label="Email address"
        orientation={orientation}
      >
        <Input type="email" placeholder="your email address" />
      </Field.Root>
    )}
  </For>
</VStack>
```

### Customize the Label

To customize the label, use `Field.Label`.

```tsx
<Field.Root>
  <Field.Label color="success">Email address</Field.Label>
  <Input type="email" placeholder="your email address" />
</Field.Root>
```

### Customize the Required Indicator

To customize the required indicator, set a `ReactNode` to `requiredIndicator`.

```tsx
<VStack>
  <Field.Root
    label="Email address"
    required
    requiredIndicator={
      <Tag colorScheme="red" size="sm">
        required
      </Tag>
    }
  >
    <Input type="email" placeholder="your email address" />
  </Field.Root>

  <Field.Root required>
    <Field.Label
      requiredIndicator={
        <Tag colorScheme="red" size="sm">
          required
        </Tag>
      }
    >
      Email address
    </Field.Label>
    <Input type="email" placeholder="your email address" />
  </Field.Root>
</VStack>
```

### Use Optional Indicator

To use an optional indicator, set a `ReactNode` to `optionalIndicator`.

```tsx
<VStack>
  <Field.Root
    label="Email address"
    optionalIndicator={<Tag size="sm">optional</Tag>}
  >
    <Input type="email" placeholder="your email address" />
  </Field.Root>

  <Field.Root>
    <Field.Label optionalIndicator={<Tag size="sm">optional</Tag>}>
      Email address
    </Field.Label>
    <Input type="email" placeholder="your email address" />
  </Field.Root>
</VStack>
```

## Uses Components & Hooks

<Uses name="field" />

## Used By Components & Hooks

<UsedBy name="field" />

## Props

<PropsTable name="field" />

## Accessibility

### ARIA Roles and Attributes

| Component                | Roles and Attributes  | Usage                                              |
| ------------------------ | --------------------- | -------------------------------------------------- |
| `FieldRequiredIndicator` | `role="presentation"` | Indicates that this is a presentation element.     |
|                          | `aria-hidden`         | Excludes the element from the accessibility tree.  |
| `Field.ErrorMessage`     | `aria-live="polite"`  | Indicates that it may be updated outside of focus. |