Field

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

Email address

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

Usage

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

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

import { Field } from "@workspaces/ui"

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

Displaying a Helper Message

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

Email addressWe'll never share your email.

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

Email addressWe'll never share your email.

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

Email addressEmail is required.

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

Email addressEmail is required.

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

Email addressEmail is required.

Email addressWe'll never share your email.Email is required.

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

Email addressWe'll never share your email.

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

Email addressWe'll never share your email.

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

Email addressWe'll never share your email.

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

Email addressWe'll never share your email.

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

Email address

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

Email addressrequired

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

Email addressoptional

<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

FieldRoot

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

Prop	Default	Type / Description
`disabled`	`false`	`boolean` If `true`, the field will be disabled.
`invalid`	`false`	`boolean` If `true`, the field will be invalid.
`readOnly`	`false`	`boolean` If `true`, the field will be readonly.
`required`	`false`	`boolean` If `true`, the field will be required.
`Label`	-
`Root`	-

FieldErrorMessage

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.

FieldHelperMessage

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.

FieldLabel

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

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.