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

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

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.

Similar Components

Fieldset is a component used to group elements such as legends, helper messages, and error messages in a fieldset element.

Form is a component used to group multiple form elements.

Bleed is a component used to extend elements beyond the boundaries of a container.

Box is the most abstract component on which all other components are built. By default, it renders a div element.

Center is a component that aligns the child elements in the center within the component.

Container is a component used as a general division element. By default, it renders the section element.

Flex is a component that sets flex to Box. Also, convenient style shorthand is available.

Float is a component used to fix elements to the edges of a container.

Uses Components & Hooks

Fieldset is a component used to group elements such as legends, helper messages, and error messages in a fieldset element.

Form is a component used to group multiple form elements.

Used By Components & Hooks

Autocomplete is a component used to display suggestions in response to user text input.

Calendar is a component for displaying or selecting dates in a calendar.

Checkbox is a component used for allowing users to select multiple values from multiple options.

ColorPicker is a component used by the user to select a color or enter an arbitrary color value.

DatePicker is a component used for users to select a date.

Dropzone is a component used for uploading files via drag and drop.

Editable is a component used to obtain inline editable text input.

Fieldset is a component used to group elements such as legends, helper messages, and error messages in a fieldset element.

FileButton is a button component used for users to select files.

FileInput is a component used for users to select files.

Input is a component used to obtain text input from the user.

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 is a component used to obtain numeric input from the user.

PasswordInput is a component that allows users to input passwords with a visibility toggle.

PinInput is a component used to capture pin codes or OTP (One-Time Password) inputs.

Radio is a component used for allowing users to select one option from multiple choices.

Rating is a component used to allow users to provide ratings.

SaturationSlider is a component used to allow the user to select a color saturation.

SegmentedControl is a component used for allowing users to select one option from multiple choices.

Select is a component used for allowing a user to choose values from a list of options.

Slider is a component used for allowing users to select a value from a range.

Switch is a component used to toggle between on and off states.

Textarea is a component used to obtain multi-line text input.

Toggle is a component that has two states: on or off.