Form
Submit information with accessible interactive controls in React. Take advantage of the browser's built-in validation with screen reader support. This component is based on the WAI-ARIA Form Role.
API
Submitting the form
The useFormStore
function returns a useSubmit
hook that can be used to register a submit handler on the form store. All registered handlers run when the user submits the form or the program calls the submit
function.
Submit handlers may return a promise and interact with the form store. This means we can access the form values
and call methods such as setErrors
to display errors when the form is submitted:
form.useSubmit(async (state) => {
const response = await fetch("https://jsonplaceholder.typicode.com/posts", {
method: "POST",
body: JSON.stringify(state.values),
headers: {
"Content-type": "application/json; charset=UTF-8",
},
});
if (!response.ok) {
form.setErrors(await response.json());
}
});
Validating the form
Built-in validation
Ariakit supports the browser's built-in validation. We can use props like required
, minLength
, maxLength
, min
, max
, type
, and pattern
to add simple validation to our form fields.
This method has a great advantage: the error messages are automatically localized to the user's language by the browser. However, the default UI doesn't necessarily follow accessibility standards. Also, the style of the error messages is not customizable, and we can't control when they are displayed.
Thankfully, JavaScript allows us to hook into this validation process using the Constraint Validation API, which FormControl
uses internally. This way, we can display the error messages in a way that is accessible and customizable.
Custom validation
Similar to Submitting the form, the useFormStore
function also returns a useValidate
hook that can be used to register a validation handler on the form store.
We can pass this hook to other components as a prop to create field-level validations:
function MyForm() {
return (
);
}
function NameInput({ store, name, ...props }) {
store.useValidate(() => {
const value = store.getValue(name);
if (value.length < 3) {
store.setError(name, "Name must be at least 3 characters long");
}
});
}
Styling
Styling the invalid state
The FormControl
component — which is used by FormInput
, FormCheckbox
, FormRadio
, and other form components — sets the aria-invalid
attribute to true
when the field is invalid. You can use this attribute to style the invalid state:
.field[aria-invalid="true"] {
/* ... */
}
Learn more on the Styling guide.