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

# Field

`Field` is a component used to group form elements with label, helper message, error message, etc.

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

## Props

### Field.Root

| Prop                 | Default | Type                                                                                                                                                         | Description                                                               |
| -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `as`                 | -       | `As`                                                                                                                                                         | The HTML element to render.                                               |
| `asChild`            | -       | `boolean`                                                                                                                                                    | Merges its props onto its immediate child.                                |
| `css`                | -       | `CSSObject \| CSSObject[]`                                                                                                                                   | The CSS object.                                                           |
| `colorScheme`        | -       | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...`                                    | Set color scheme variables.                                               |
| `disabled`           | `false` | `boolean`                                                                                                                                                    | If `true`, the field will be disabled.                                    |
| `errorMessage`       | -       | `ReactNode`                                                                                                                                                  | The field error message to use.                                           |
| `errorMessageProps`  | -       | `FieldErrorMessageProps`                                                                                                                                     | Props the error message component.                                        |
| `helperMessage`      | -       | `ReactNode`                                                                                                                                                  | The field helper message to use.                                          |
| `helperMessageProps` | -       | `FieldHelperMessageProps`                                                                                                                                    | Props the helper message component.                                       |
| `invalid`            | `false` | `boolean`                                                                                                                                                    | If `true`, the field will be invalid.                                     |
| `label`              | -       | `ReactNode`                                                                                                                                                  | The field label to use.                                                   |
| `labelProps`         | -       | `FieldLabelProps`                                                                                                                                            | Props the label component.                                                |
| `name`               | -       | `string`                                                                                                                                                     | The name of the field.                                                    |
| `optionalIndicator`  | -       | `string \| number \| bigint \| boolean \| ReactElement<unknown, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal \| Promise<...>` | The optional indicator to use.                                            |
| `readOnly`           | `false` | `boolean`                                                                                                                                                    | If `true`, the field will be readonly.                                    |
| `replace`            | `true`  | `boolean`                                                                                                                                                    | If `true`, switch between helper message and error message using invalid. |
| `required`           | `false` | `boolean`                                                                                                                                                    | If `true`, the field will be required.                                    |
| `requiredIndicator`  | -       | `string \| number \| bigint \| boolean \| ReactElement<unknown, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal \| Promise<...>` | The required indicator to use.                                            |

### Field.ErrorMessage

| Prop          | Default | Type                                                                                                                      | Description                                |
| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `as`          | -       | `As`                                                                                                                      | The HTML element to render.                |
| `asChild`     | -       | `boolean`                                                                                                                 | Merges its props onto its immediate child. |
| `css`         | -       | `CSSObject \| CSSObject[]`                                                                                                | The CSS object.                            |
| `colorScheme` | -       | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` | Set color scheme variables.                |

### Field.HelperMessage

| Prop          | Default | Type                                                                                                                      | Description                                |
| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `as`          | -       | `As`                                                                                                                      | The HTML element to render.                |
| `asChild`     | -       | `boolean`                                                                                                                 | Merges its props onto its immediate child. |
| `css`         | -       | `CSSObject \| CSSObject[]`                                                                                                | The CSS object.                            |
| `colorScheme` | -       | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` | Set color scheme variables.                |

### Field.Label

| Prop                | Default | Type                                                                                                                      | Description                                |
| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `as`                | -       | `As`                                                                                                                      | The HTML element to render.                |
| `asChild`           | -       | `boolean`                                                                                                                 | Merges its props onto its immediate child. |
| `css`               | -       | `CSSObject \| CSSObject[]`                                                                                                | The CSS object.                            |
| `colorScheme`       | -       | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` | Set color scheme variables.                |
| `optionalIndicator` | -       | `ReactNode`                                                                                                               | The optional indicator to use.             |
| `required`          | `false` | `boolean`                                                                                                                 | If `true`, the field will be required.     |
| `requiredIndicator` | -       | `ReactNode`                                                                                                               | The required indicator to use.             |

## Accessibility

### ARIA Roles and Attributes

| Element                             | Roles and Attributes  | Usage                                              |
| ----------------------------------- | --------------------- | -------------------------------------------------- |
| `div.ui-field__root`                | `role="group"`        | Indicates that this is a group element.            |
| `span.ui-field__required-indicator` | `role="presentation"` | Indicates that this is a presentation element.     |
|                                     | `aria-hidden`         | Excludes the element from the accessibility tree.  |
| `span.ui-field__error-message`      | `aria-live="polite"`  | Indicates that it may be updated outside of focus. |

## Similar Components

- [Fieldset](https://yamada-ui.com/docs/components/fieldset.md): `Fieldset` is a component used to group elements such as legends, helper messages, and error messages in a fieldset element.
- [Form](https://yamada-ui.com/docs/components/form.md): `Form` is a component used to group multiple form elements.
- [Bleed](https://yamada-ui.com/docs/components/bleed.md): `Bleed` is a component used to extend elements beyond the boundaries of a container.
- [Box](https://yamada-ui.com/docs/components/box.md): `Box` is the most abstract component on which all other components are built. By default, it renders a `div` element.
- [Center](https://yamada-ui.com/docs/components/center.md): `Center` is a component that aligns the child elements in the center within the component.
- [Container](https://yamada-ui.com/docs/components/container.md): `Container` is a component used as a general division element. By default, it renders the `section` element.
- [Flex](https://yamada-ui.com/docs/components/flex.md): `Flex` is a component that sets `flex` to `Box`. Also, convenient style shorthand is available.
- [Float](https://yamada-ui.com/docs/components/float.md): `Float` is a component used to fix elements to the edges of a container.

## Uses Components & Hooks

- [Fieldset](https://yamada-ui.com/docs/components/fieldset.md): `Fieldset` is a component used to group elements such as legends, helper messages, and error messages in a fieldset element.
- [Form](https://yamada-ui.com/docs/components/form.md): `Form` is a component used to group multiple form elements.

## Used By Components & Hooks

- [Autocomplete](https://yamada-ui.com/docs/components/autocomplete.md): `Autocomplete` is a component used to display suggestions in response to user text input.
- [Calendar](https://yamada-ui.com/docs/components/calendar.md): `Calendar` is a component for displaying or selecting dates in a calendar.
- [Checkbox](https://yamada-ui.com/docs/components/checkbox.md): `Checkbox` is a component used for allowing users to select multiple values from multiple options.
- [ColorPicker](https://yamada-ui.com/docs/components/color-picker.md): `ColorPicker` is a component used by the user to select a color or enter an arbitrary color value.
- [DatePicker](https://yamada-ui.com/docs/components/date-picker.md): `DatePicker` is a component used for users to select a date.
- [Dropzone](https://yamada-ui.com/docs/components/dropzone.md): `Dropzone` is a component used for uploading files via drag and drop.
- [Editable](https://yamada-ui.com/docs/components/editable.md): `Editable` is a component used to obtain inline editable text input.
- [Fieldset](https://yamada-ui.com/docs/components/fieldset.md): `Fieldset` is a component used to group elements such as legends, helper messages, and error messages in a fieldset element.
- [FileButton](https://yamada-ui.com/docs/components/file-button.md): `FileButton` is a button component used for users to select files.
- [FileInput](https://yamada-ui.com/docs/components/file-input.md): `FileInput` is a component used for users to select files.
- [Input](https://yamada-ui.com/docs/components/input.md): `Input` is a component used to obtain text input from the user.
- [NativeSelect](https://yamada-ui.com/docs/components/native-select.md): `NativeSelect` is a component used for allowing users to select one value from a list of options. It displays a native dropdown list provided by the browser (user agent).
- [NumberInput](https://yamada-ui.com/docs/components/number-input.md): `NumberInput` is a component used to obtain numeric input from the user.
- [PasswordInput](https://yamada-ui.com/docs/components/password-input.md): `PasswordInput` is a component that allows users to input passwords with a visibility toggle.
- [PinInput](https://yamada-ui.com/docs/components/pin-input.md): `PinInput` is a component used to capture pin codes or OTP (One-Time Password) inputs.
- [Radio](https://yamada-ui.com/docs/components/radio.md): `Radio` is a component used for allowing users to select one option from multiple choices.
- [Rating](https://yamada-ui.com/docs/components/rating.md): `Rating` is a component used to allow users to provide ratings.
- [SaturationSlider](https://yamada-ui.com/docs/components/saturation-slider.md): `SaturationSlider` is a component used to allow the user to select a color saturation.
- [SegmentedControl](https://yamada-ui.com/docs/components/segmented-control.md): `SegmentedControl` is a component used for allowing users to select one option from multiple choices.
- [Select](https://yamada-ui.com/docs/components/select.md): `Select` is a component used for allowing a user to choose values from a list of options.
- [Slider](https://yamada-ui.com/docs/components/slider.md): `Slider` is a component used for allowing users to select a value from a range.
- [Switch](https://yamada-ui.com/docs/components/switch.md): `Switch` is a component used to toggle between on and off states.
- [Textarea](https://yamada-ui.com/docs/components/textarea.md): `Textarea` is a component used to obtain multi-line text input.
- [Toggle](https://yamada-ui.com/docs/components/toggle.md): `Toggle` is a component that has two states: on or off.