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 isInvalid to true and assign a ReactNode to errorMessage.

Editable example

<FormControl isInvalid 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 isInvalid 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 isInvalid is true. To replace the help message with the error message when the error message is displayed, set isReplace to true.

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

Editable example

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

Copied!

Making it Required

To make it required, set isRequired to true.

Editable example

<FormControl
  isRequired
  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 isDisabled to true.

Editable example

<FormControl
  isDisabled
  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 isReadOnly to true.

Editable example

<FormControl
  isReadOnly
  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
    isRequired
    label="Email address"
    requiredIndicator={
      <Tag size="sm" colorScheme="red" ms={2}>
        required
      </Tag>
    }
  >
    <Input type="email" placeholder="your email address" />
  </FormControl>

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