FormControl

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

Import

import {
  FormControl,
  Label,
  HelperMessage,
  ErrorMessage,
} from "@yamada-ui/react"

Copied!

FormControl: A wrapper component that controls child elements (Label, HelperMessage, ErrorMessage).
Label: A component for labels used in form sections. htmlFor is automatically assigned to child elements.
HelperMessage: A component that displays a description for a form section.
ErrorMessage: A component displayed when an error occurs.

Label, HelperMessage, and ErrorMessage can be omitted.

Usage

Editable example

<FormControl label="Email address">
  <Input type="email" placeholder="your email address" />
</FormControl>

Copied!

Or, you can customize it using Label.

Editable example

<FormControl helperMessage="We'll never share your email.">
  <Label color="primary">Email address</Label>
  <Input type="email" placeholder="your email address" />
</FormControl>

Copied!

Displaying a Help Message

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

Editable example

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

Copied!

Or, you can customize it using HelperMessage.

Editable example

<FormControl label="Email address">
  <Input type="email" placeholder="your email address" />
  <HelperMessage color="gray.300">We'll never share your email.</HelperMessage>
</FormControl>

Copied!

Displaying an Error Message

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

Editable example

<FormControl invalid label="Email address" errorMessage="Email is required.">
  <Input type="email" placeholder="your email address" />
</FormControl>

Copied!

Or, you can customize it using ErrorMessage.

Editable example

<FormControl invalid label="Email address">
  <Input type="email" placeholder="your email address" />
  <ErrorMessage color="gray.300">Email is required.</ErrorMessage>
</FormControl>

Copied!

Replacing Help Message with Error Message

Error messages are displayed only when invalid is true. To replace the help message with the error message when the error message is displayed, set replace to true.

Use the replace property to replace the help message with the error message.

Editable example

<FormControl
  invalid
  label="Email address"
  helperMessage="We'll never share your email."
  errorMessage="Email is required."
  replace={true}
>
  <Input type="email" placeholder="your email address" />
</FormControl>

Copied!

Making it Required

To make it required, set required to true.

Editable example

<FormControl
  required
  label="Email address"
  helperMessage="We'll never share your email."
  errorMessage="Email is required."
>
  <Input type="email" placeholder="your email address" />
</FormControl>

Copied!

Disabling

To disable it, set disabled to true.

Editable example

<FormControl
  disabled
  label="Email address"
  helperMessage="We'll never share your email."
  errorMessage="Email is required."
>
  <Input type="email" placeholder="your email address" />
</FormControl>

Copied!

Making it Read-Only

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

Editable example

<FormControl
  readOnly
  label="Email address"
  helperMessage="We'll never share your email."
  errorMessage="Email is required."
>
  <Input type="email" placeholder="your email address" />
</FormControl>

Copied!

Customizing the Required Indicator

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

Editable example

<VStack>
  <FormControl
    required
    label="Email address"
    requiredIndicator={
      <Tag size="sm" colorScheme="red" ms={2}>
        required
      </Tag>
    }
  >
    <Input type="email" placeholder="your email address" />
  </FormControl>

  <FormControl required>
    <Label
      requiredIndicator={
        <Tag size="sm" colorScheme="red" ms={2}>
          required
        </Tag>
      }
    >
      Email address
    </Label>
    <Input type="email" placeholder="your email address" />
  </FormControl>
</VStack>

Copied!

Using an Optional Indicator

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

Editable example

<VStack>
  <FormControl
    label="Email address"
    optionalIndicator={
      <Tag size="sm" colorScheme="primary" ms={2}>
        optional
      </Tag>
    }
  >
    <Input type="email" placeholder="your email address" />
  </FormControl>

  <FormControl>
    <Label
      optionalIndicator={
        <Tag size="sm" colorScheme="primary" ms={2}>
          optional
        </Tag>
      }
    >
      Email address
    </Label>
    <Input type="email" placeholder="your email address" />
  </FormControl>
</VStack>

Copied!

Edit this page on GitHub

PreviousForms NextFieldset