Color Schemes for FormControl
are not implemented in the default theme. You can extend the theme to implement them.
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/react'
Usage#
<FormControl id='email'><FormLabel>Email address</FormLabel><Input type='email' /><FormHelperText>We'll never share your email.</FormHelperText></FormControl>
Sample usage for a radio or checkbox group#
<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>
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.
<FormControl id='first-name' isRequired><FormLabel>First name</FormLabel><Input placeholder='First name' /></FormControl>
Select Example#
<FormControl id='country'><FormLabel>Country</FormLabel><Select placeholder='Select country'><option>United Arab Emirates</option><option>Nigeria</option></Select></FormControl>
Number Input Example#
<FormControl id='amount'><FormLabel>Amount</FormLabel><NumberInput max={50} min={10}><NumberInputField /><NumberInputStepper><NumberIncrementStepper /><NumberDecrementStepper /></NumberInputStepper></NumberInput></FormControl>
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 errorif (!value) {error = 'Name is required'} else if (value.toLowerCase() !== 'naruto') {error = "Jeez! You're not a fan 😱"}return error}return (<FormikinitialValues={{ 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><Buttonmt={4}colorScheme='teal'isLoading={props.isSubmitting}type='submit'>Submit</Button></Form>)}</Formik>)}
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 havehtmlFor
that points to theid
of the form input.FormErrorMessage
addsaria-describedby
andaria-invalid
pointing to the form input.FormHelperText
adds/extendsaria-describedby
pointing to the form input.isDisabled
,isRequired
,isReadOnly
props passed toFormControl
will cascade across all related components.
-
FormLabel
is now aware of thedisabled
,focused
anderror
state of the form input. This helps you style the label accordingly using the_disabled
,_focus
, and_invalid
style props. -
If you render
FormErrorMessage
andisInvalid
isfalse
orundefined
,FormErrorMessage
won't be visible. The only way to make it visible is by passingisInvalid
and setting it totrue
.
Props#
colorScheme
colorScheme
string
isDisabled
isDisabled
If true
, the form control will be disabled. This has 2 side effects:
- The FormLabel
will have `data-disabled` attribute
- The form element (e.g, Input) will be disabled
boolean
isInvalid
isInvalid
If true
, the form control will be invalid. This has 2 side effects:
- The FormLabel
and FormErrorIcon
will have `data-invalid` set to true
- The form element (e.g, Input) will have `aria-invalid` set to true
boolean
isReadOnly
isReadOnly
If true
, the form control will be readonly
boolean
isRequired
isRequired
If true
, the form control will be required. This has 2 side effects:
- The FormLabel
will show a required indicator
- The form element (e.g, Input) will have `aria-required` set to true
boolean
label
label
The label text used to inform users as to what information is requested for a text field.
string
size
size
string
variant
variant
string