Form
The
Form component groups and manages related form fields together. The 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.Basic usage
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.Task-backed forms
A common use for
Form is to execute a task when the form is submitted. If the slug of an existing
task is passed to the form via the task prop, the form will automatically populate itself with the
appropriate fields based on the task parameters. Then, when the form is submitted, the form executes
the associated task.Forms can also execute runbooks when a runbook is passed via the
runbook prop.Customizing fields
The fields of a task- or runbook-backed form can be customized using the field slugs. This can be
helpful when the associated task or runbook has a lot of parameters, or if the values of some
parameters are known ahead of time.
- If set, only fields in
shownFieldswill be displayed. - Fields in
hiddenFieldswill be hidden. fieldOptionscan be used to constrain the values of a field or set a default value.
Note that if a parameter is required, but not displayed in the form, its value must be set in one of
the field options.
Manually executing a task
The standard task-backed form should be used whenever a task should be run on form submit, using the
form values. If manual control over task execution or transformations on the form values are needed,
useTaskMutation can be used in conjunction with
a standard form.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.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.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.
Resetting form field values
By default, the form will reset its field values when the form is submitted. You can disable this
behavior by setting the
resetOnSubmit prop to false.We also provide a
reset method on the form's state API that you can call to programmatically reset
form field values.Supported input components
- Checkbox
- Code input
- Date picker
- Date and time picker
- File input
- Multi select
- Number input
- Radio group
- Select
- Slider
- Switch
- Text input
- Textarea
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. | Submit |
| 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 |
| disabled | boolean If true, the submit button is always disabled. The submit button may disabled even if this is
set to false, for example if the form has errors or if the user does not have permission to
submit a task-backed form. | |
| submitting | boolean If true, the submit button is disabled and a spinner is shown.
This is set automatically when using a task-backed form. | |
| 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%. | |
| task | string
| {
slug: string;
shownFields?: string[];
hiddenFields?: string[];
fieldOptions?: {
slug: string;
value?: string | number | boolean | Date;
defaultValue?: string | number | Date;
allowedValues?: string[] | number[] | Date[];
}[];
} The task associated with the form. This can either be a string, corresponding to the task slug, or an options struct, for which the task slug must be passed in the slug field. If shownFields is set, only fields in shownFields are shown. If hiddenFields is set, fields in hiddenFields are hidden.fieldOptions can be used to configure the values for a field. Each option in fieldOptions has a slug field, corresponding to the parameter slug. | |
| runbook | string
| {
slug: string;
shownFields?: string[];
hiddenFields?: string[];
fieldOptions?: {
slug: string;
value?: string | number | boolean | Date;
defaultValue?: string | number | Date;
allowedValues?: string[] | number[] | Date[];
}[];
} The runbook associated with the form. This can either be a string, corresponding to the runbook slug, or an options struct, for which the runbook slug must be passed in the slug field. If shownFields is set, only fields in shownFields are shown. If hiddenFields is set, fields in hiddenFields are hidden.fieldOptions can be used to configure the values for a field. Each option in fieldOptions has a slug field, corresponding to the parameter slug. |
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 |