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#
Chakra UI exports 4 components for Form Control:
FormControl: The wrapper that provides context and functionality for all children.FormLabel: The label of a form section. The usage is similar to html label.FormHelperText: The message that tells users more details about the form section.FormErrorMessage: The message that shows up when an error occurs.
import {FormControl,FormLabel,FormErrorMessage,FormHelperText,} from '@chakra-ui/react'
Usage#
<FormControl><FormLabel htmlFor='email'>Email address</FormLabel><Input id='email' 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>
Error message#
FormErrorMessage will only show up when the property isInvalid in
FormControl is true.
function errorMessageExample() {const [input, setInput] = useState('')const handleInputChange = (e) => setInput(e.target.value)const isError = input === ''return (<FormControl isInvalid={isError}><FormLabel htmlFor='email'>Email</FormLabel><Inputid='email'type='email'value={input}onChange={handleInputChange}/>{!isError ? (<FormHelperText>Enter the email you'd like to receive the newsletter on.</FormHelperText>) : (<FormErrorMessage>Email is required.</FormErrorMessage>)}</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. This red asterisk can be
overwritten by passing requiredIndicator to the FormLabel. If you want to
indicate that a field is optional you can add optionalIndicator to the
FormLabel
<FormControl isRequired><FormLabel htmlFor='first-name'>First name</FormLabel><Input id='first-name' placeholder='First name' /></FormControl>
Select Example#
<FormControl><FormLabel htmlFor='country'>Country</FormLabel><Select id='country' placeholder='Select country'><option>United Arab Emirates</option><option>Nigeria</option></Select></FormControl>
Number Input Example#
<FormControl><FormLabel htmlFor='amount'>Amount</FormLabel><NumberInput max={50} min={10}><NumberInputField id='amount' /><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
FormControlcomponent. Here are the changes:idpassed to the form control will be passed to the form input directly.FormLabelwill havehtmlForthat points to theidof the form input.FormErrorMessageaddsaria-describedbyandaria-invalidpointing to the form input.FormHelperTextadds/extendsaria-describedbypointing to the form input.isDisabled,isRequired,isReadOnlyprops passed toFormControlwill cascade across all related components.
-
FormLabelis now aware of thedisabled,focusedanderrorstate of the form input. This helps you style the label accordingly using the_disabled,_focus, and_invalidstyle props. -
If you render
FormErrorMessageandisInvalidisfalseorundefined,FormErrorMessagewon't be visible. The only way to make it visible is by passingisInvalidand setting it totrue.
Props#
colorScheme
colorScheme(string & {})isDisabled
isDisabledIf 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
booleanisInvalid
isInvalidIf 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
booleanisReadOnly
isReadOnlyIf true, the form control will be readonly
booleanisRequired
isRequiredIf 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
booleanlabel
labelThe label text used to inform users as to what information is requested for a text field.
stringsize
sizeSizes for FormControl are not implemented in the default theme. You can extend the theme to implement them.
stringvariant
variantVariants for FormControl are not implemented in the default theme. You can extend the theme to implement them.
string