Form
Group and manage form fields with the Form component
Basic usage
Form groups related input components together. Additionally, Form manages the state of its
fields, making it a convenient way to submit user input without having to write individual event
handlers for each input.Try entering values in the form below and clicking "Submit". A map of the form field IDs to their
values passed to the
onSubmit handler.Loading view...
Validation
Required inputs
Form can be used to validate user input. All form fields take the required prop, which indicates
that the input must be filled out before the form can be successfully submitted.Loading view...
Custom validation
All form fields support custom validation functions. The
validate prop an input take a function or
list of functions. The function(s) take in the input's value. If the function(s) return a string,
the input is considered invalid.Form will automatically validate its fields on submit.Loading view...
Dependent fields validation
You have access to all of a form's values by tapping into the component state for the form. This
way, you can set up custom validation for dependent form fields.
Loading view...
Resetting form field values
Set the form's
resetOnSubmit prop to true to reset all form field values to their initial
values. This is useful if you want to clear the form after a successful submission.Try changing the fields below and submitting the form below to see this in action.
Loading view...
We also provide a
reset method on the form's state API that you can call to reset form field
values.Loading view...
Supported input components
Component API
| Name | Description | Default |
|---|---|---|
| id | string The ID referenced by the global component state | |
| children | Component The form children | |
| submitText | string Label on the form's submit button | |
| onSubmit | (state: State) => void Callback for when the form is submitted.
The callback is passed the form's input state as input. | |
| resetOnSubmit | boolean If true, the form input state will be reset to their initial values on submit. | true |
| width | number | "content" | "auto" | `${number}%` | `${number}/${number}` | { xs?: ColWidth; sm?: ColWidth; md?: ColWidth; lg?: ColWidth; xl?: ColWidth; } Width of the component. This component must be a direct child of a <Stack> for this prop to take effect.
If an integer is specified, signifies the width in a 12 item grid. 12 means that the component takes up
the entire row, 6 is half, 1 is 1/12.
If a decimal or fraction is specified, signifies the fractional share of the row. e.g. 1/2 takes up half of the row.
If a percentage is specified, signifies the percentage share of the row. e.g. "50%" takes up half of the row.
content indicates that the component should take up as much space as its content.
auto indicates that the component should take any leftover space on the row.
To set width based on the screen size, use an object with a specific width for each breakpoint.
e.g. {xs: "100%", md: "50%"} sets the width on xs-md screens to 100% and md and larger screens to 50%. | content |
| offset | number | `${number}%` | `${number}/${number}` | { xs?: ColOffset; sm?: ColOffset; md?: ColOffset; lg?: ColOffset; xl?: ColOffset; } Creates a gap to the left of the component. Has the same units as width. This component must be a direct child of a <Stack> for this prop to take effect.
If an integer is specified, signifies the offset in a 12 item grid. 6 means the component is offset by half a row, 1 is 1/12 of a row.
If a decimal or fraction is specified, signifies the fractional share of the row. e.g. 1/2 offsets a component by half of the row.
If a percentage is specified, signifies the percentage share of the row. e.g. "50%" offsets a component by half of the row.
To set offset based on the screen size, use an object with a specific offset for each breakpoint.
e.g. {xs: "50%", md: "0%"} sets the offset on xs-md screens to 50% and md and larger screens to 0%. |
State API
| Name | Description |
|---|---|
| values | Record<string, any> Map of the form's input IDs to their values |
| reset | () => void Function to reset all of the form's inputs |