Form Control

FormControl provides context such as isInvalid, isDisabled, and isRequired to form elements.

It follows the WAI specifications for forms.

Import#

import {
  FormControl,
  FormLabel,
  FormErrorMessage,
  FormHelperText,
} from "@chakra-ui/core"

import {
  FormControl,
  FormLabel,
  FormErrorMessage,
  FormHelperText,
} from "@chakra-ui/core"

Usage#

Email address

We'll never share your email.

<FormControl id="email">
  <FormLabel>Email address</FormLabel>
  <Input type="email" />
  <FormHelperText>We'll never share your email.</FormHelperText>
</FormControl>

<FormControl id="email">
  <FormLabel>Email address</FormLabel>
  <Input type="email" />
  <FormHelperText>We'll never share your email.</FormHelperText>
</FormControl>

Editable Example

Sample usage for a radio or checkbox group#

Favorite Naruto Character

Sasuke

Nagato

Itachi

Sage of the six Paths

Select only if you're a fan.

<FormControl as="fieldset">
  <FormLabel as="legend">Favorite Naruto Character</FormLabel>
  <RadioGroup defaultValue="Itachi">
    <HStack spacing="24px">
      <Radio value="Sasuke">Sasuke</Radio>
      <Radio value="Nagato">Nagato</Radio>
      <Radio value="Itachi">Itachi</Radio>
      <Radio value="Sage of the six Paths">Sage of the six Paths</Radio>
    </HStack>
  </RadioGroup>
  <FormHelperText>Select only if you're a fan.</FormHelperText>
</FormControl>

<FormControl as="fieldset">
  <FormLabel as="legend">Favorite Naruto Character</FormLabel>
  <RadioGroup defaultValue="Itachi">
    <HStack spacing="24px">
      <Radio value="Sasuke">Sasuke</Radio>
      <Radio value="Nagato">Nagato</Radio>
      <Radio value="Itachi">Itachi</Radio>
      <Radio value="Sage of the six Paths">Sage of the six Paths</Radio>
    </HStack>
  </RadioGroup>
  <FormHelperText>Select only if you're a fan.</FormHelperText>
</FormControl>

Editable Example

Making a field required#

By passing the isRequired props, the Input field has aria-required set to true, and the FormLabel will show a red asterisk.

First name

<FormControl id="first-name" isRequired>
  <FormLabel>First name</FormLabel>
  <Input placeholder="First name" />
</FormControl>

<FormControl id="first-name" isRequired>
  <FormLabel>First name</FormLabel>
  <Input placeholder="First name" />
</FormControl>

Editable Example

Select Example#

Country

<FormControl id="country">
  <FormLabel>Country</FormLabel>
  <Select placeholder="Select country">
    <option>United Arab Emirates</option>
    <option>Nigeria</option>
  </Select>
</FormControl>

<FormControl id="country">
  <FormLabel>Country</FormLabel>
  <Select placeholder="Select country">
    <option>United Arab Emirates</option>
    <option>Nigeria</option>
  </Select>
</FormControl>

Editable Example

Number Input Example#

Amount

<FormControl id="amount">
  <FormLabel>Amount</FormLabel>
  <NumberInput max={50} min={10}>
    <NumberInputField />
    <NumberInputStepper>
      <NumberIncrementStepper />
      <NumberDecrementStepper />
    </NumberInputStepper>
  </NumberInput>
</FormControl>

<FormControl id="amount">
  <FormLabel>Amount</FormLabel>
  <NumberInput max={50} min={10}>
    <NumberInputField />
    <NumberInputStepper>
      <NumberIncrementStepper />
      <NumberDecrementStepper />
    </NumberInputStepper>
  </NumberInput>
</FormControl>

Editable Example

Usage with Form Libraries#

Form Libraries like Formik make it soooo easy to manage form state and validation. I 💖 Formik

function FormikExample() {
  function validateName(value) {
    let error
    if (!value) {
      error = "Name is required"
    } else if (value !== "Naruto") {
      error = "Jeez! You're not a fan 😱"
    }
    return error
  }

  return (
    <Formik
      initialValues={{ name: "Sasuke" }}
      onSubmit={(values, actions) => {
        setTimeout(() => {
          alert(JSON.stringify(values, null, 2))
          actions.setSubmitting(false)
        }, 1000)
      }}
    >
      {(props) => (
        <Form>
          <Field name="name" validate={validateName}>
            {({ field, form }) => (
              <FormControl isInvalid={form.errors.name && form.touched.name}>
                <FormLabel htmlFor="name">First name</FormLabel>
                <Input {...field} id="name" placeholder="name" />
                <FormErrorMessage>{form.errors.name}</FormErrorMessage>
              </FormControl>
            )}
          </Field>
          <Button
            mt={4}
            colorScheme="teal"
            isLoading={props.isSubmitting}
            type="submit"
          >
            Submit
          </Button>
        </Form>
      )}
    </Formik>
  )
}

function FormikExample() {
  function validateName(value) {
    let error
    if (!value) {
      error = "Name is required"
    } else if (value !== "Naruto") {
      error = "Jeez! You're not a fan 😱"
    }
    return error
  }
  return (
    <Formik
      initialValues={{ name: "Sasuke" }}
      onSubmit={(values, actions) => {
        setTimeout(() => {
          alert(JSON.stringify(values, null, 2))
          actions.setSubmitting(false)
        }, 1000)
      }}
    >
      {(props) => (
        <Form>
          <Field name="name" validate={validateName}>
            {({ field, form }) => (
              <FormControl isInvalid={form.errors.name && form.touched.name}>
                <FormLabel htmlFor="name">First name</FormLabel>
                <Input {...field} id="name" placeholder="name" />
                <FormErrorMessage>{form.errors.name}</FormErrorMessage>
              </FormControl>
            )}
          </Field>
          <Button
            mt={4}
            colorScheme="teal"
            isLoading={props.isSubmitting}
            type="submit"
          >
            Submit
          </Button>
        </Form>
      )}
    </Formik>
  )
}

Editable Example

Improvements from v1#

We've improved the accessibility of the FormControl component. Here are the changes:
- id passed to the form control will be passed to the form input directly
- FormLabel will have htmlFor that points to the id of the form input
- FormErrorMessage adds aria-describedby and aria-invalid pointing to the form input
- FormHelperText adds/extends aria-describedby pointing to the form input
- isDisabled, isRequired, isReadOnly props passed to FormControl will cascade across all related components
FormLabel is now aware of the disabled, focused and error state of the form input. This helps you style the label accordingly using the _disabled, _focus, and _invalid style props.
If you render FormErrorMessage and isInvalid is false or undefined, FormErrorMessage won't be visible. The only way to make it visible is by passing isInvalid and setting it to true.

Props#

Name	Type	Description
`isInvalid`	`boolean`	If `true`, this prop is passed to its children.
`isRequired`	`boolean`	If `true`, this prop is passed to its children.
`isDisabled`	`boolean`	If `true`, this prop is passed to its children.
`isReadOnly`	`boolean`	If `true`, this prop is passed to its children.

Edit this page

Form Control

.css-12m0k8p{pointer-events:auto;}Import.css-1l2j62r{color:#319795;font-weight:400;outline:none;opacity:0;margin-left:0.375rem;}.css-1l2j62r:focus,.css-1l2j62r[data-focus]{opacity:1;box-shadow:0 0 0 3px rgba(66,153,225,0.6);}#

Usage#

Sample usage for a radio or checkbox group#

Making a field required#

Select Example#

Number Input Example#

Usage with Form Libraries#

Improvements from v1#

Props#

Import#