Form Control
Form Control provides context such as isInvalid
, isDisabled
, and
isRequired
to form elements
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.htmlFor
is set by default for children input.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>Email address</FormLabel>
<Input type='email' />
<FormHelperText>We'll never share your email.</FormHelperText>
</FormControl>
Sample usage for a radio or checkbox group
Error message
FormErrorMessage
will only show up when the property isInvalid
in
FormControl
is true.
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
Select Example
Number Input Example
Usage with Form Libraries
Form Libraries like Formik make it soooo easy to manage form state and validation. I 💖 Formik
// The below import defines which components come from formik
// import { Field, Form, Formik } from 'formik';
function FormikExample() {
function validateName(value) {
let error;
if (!value) {
error = 'Name is required';
} else if (value.toLowerCase() !== '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>First name</FormLabel>
<Input {...field} placeholder='name' />
<FormErrorMessage>{form.errors.name}</FormErrorMessage>
</FormControl>
)}
</Field>
<Button
mt={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
.You can still supply an
id
prop toFormControl
that will override the randomly generatedid
and attach to thefor
attribute of the label and theid
of the form element. (It also affects theid
attribute of the label)The combination of
htmlFor
andid
are optional in which adding both will also override the generatedid
sent to the provider.
Props
colorScheme
colorScheme
Color Schemes for FormControl
are not implemented in the default theme. You can extend the theme to implement them.
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
Sizes for FormControl
are not implemented in the default theme. You can extend the theme to implement them.
string
variant
variant
Variants for FormControl
are not implemented in the default theme. You can extend the theme to implement them.
string