Form
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
onSubmit
handler.tsxCopied1<Form2onSubmit={(values) => {3alert(`Submitted with values: ${JSON.stringify(values)}`);4}}5>6<TextInput id="name" label="Cat name" />7<Select8id="breed"9label="Breed"10data={["American Wirehair", "British Shorthair", "Taby"]}11/>12</Form>
Task-backed forms
Form
is to execute a task when the form is submitted. If the slug of an existing
task or an AirplaneFunc
(output of
airplane.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.runbook
prop.tsxCopied1return <Form task="pet_cat" />;
tsxCopied1const petCat = airplane.task(...);2return <Form task={petCat} />;
tsxCopied1return <Form runbook="pet_cat" />;
Accessing autogenerated inputs on the component state
.
delimiter. This id can be used to manipulate
the input values using the component state.tsxCopied1const { id, values } = useComponentState("formid");2const { value, setValue } = useComponentState("formid.num_times");3return (4<Stack>5<Form id={id} task="pet_cat" />6<Button onClick={() => setValue(value ? value + 1 : 1)}>More pets</Button>7<Text>{JSON.stringify(values)}</Text>8<Text>{value}</Text>9</Stack>10);
beforeSubmitTransform
and onSubmit
, will be keyed according to the original
parameter slugs.Customizing fields
- If set, only fields in
shownFields
will be displayed. - Fields in
hiddenFields
will be hidden. fieldOptions
can be used to constrain the values of a field, set a default value, or set a validation function.
tsxCopied1return (2<Form3task={{4slug: "pet_cat",5hiddenFields: ["num_times"],6fieldOptions: [7{ slug: "num_times", value: 1 },8{ slug: "name", defaultValue: "Bootz", allowedValues: ["Bootz", "Hazel", "Baosky"] },9],10}}11/>12);
Calling a task with useTaskMutation
useTaskMutation
can be used in
conjunction with a standard form.tsxCopied1const { id, values } = useComponentState();2const { output, mutate } = useTaskMutation({ slug: "search_animals", params: values });3return (4<Stack>5<Form6id={id}7onSubmit={() => {8mutate();9}}10>11<Select id="animal" required label="Animal" data={[{ value: "cat", label: "Cat" }]} />12</Form>13{output && <Table data={output} />}14</Stack>15);
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.tsxCopied1<Form2onSubmit={(values) => {3alert(`Submitted with values: ${JSON.stringify(values)}`);4}}5>6<TextInput required id="name" label="Cat name" />7<Select8required9id="breed"10label="Breed"11data={["American Wirehair", "British Shorthair", "Taby"]}12/>13</Form>
Custom validation
validate
prop on an input takes a
function or list of functions, each of which takes in the input's value. If the function(s) return a
string, the input is considered invalid. To add validation to a task-backed form, set the
fieldOptions
.Form
will automatically validate its fields on submit.tsxCopied1<Form2onSubmit={(values) => {3alert(`Submitted with values: ${JSON.stringify(values)}`);4}}5>6<TextInput7id="name"8label="Cat name"9defaultValue="Spot"10validate={[validateLength, validateNoSpot]}11/>12<Select13required14id="breed"15label="Breed"16defaultValue="Taby"17data={["American Wirehair", "British Shorthair", "Taby"]}18validate={validateNoTaby}19/>20</Form>
Dependent fields validation
tsxCopied1const { id, values } = useComponentState();2return (3<Stack>4<Form5id={id}6onSubmit={(values) => {7alert(`Submitted with values: ${JSON.stringify(values)}`);8}}9>10<TextInput id="name" label="Cat name" defaultValue="Sir Reginald" />11<Select12required13id="breed"14label="Breed"15defaultValue="American Wirehair"16data={["American Wirehair", "British Shorthair", "Taby"]}17validate={(value) => {18if (values?.name && values?.name.startsWith("Sir") && value !== "British Shorthair") {19return "Only British Shorthairs are allowed to be named Sir";20}21}}22/>23</Form>24</Stack>25);
Resetting form field values
resetOnSubmit
prop to false
.tsxCopied1<Form2resetOnSubmit={false}3onSubmit={(values) => {4alert(`Submitted with values: ${JSON.stringify(values)}`);5}}6>7<TextInput id="name" label="Cat name" />8<Select9id="breed"10label="Breed"11// Resetting the form will reset the selected value to the defaultValue.12// In this case, the value after reset will be "Taby"13defaultValue="Taby"14data={["American Wirehair", "British Shorthair", "Taby"]}15/>16</Form>
reset
method on the form's state API that you can call to programmatically reset
form field values.tsxCopied1const { id, reset } = useComponentState();2return (3<Stack>4<Form5id={id}6submitText="Reset"7onSubmit={() => {8reset();9}}10>11<TextInput id="name" label="Cat name" />12<Select13id="breed"14label="Breed"15defaultValue="Taby"16data={["American Wirehair", "British Shorthair", "Taby"]}17/>18</Form>19</Stack>20);
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
Function applied to transform the form's input state before being passed to onSubmit. This will affect the parameters received by the task for a task-backed form.
The form children.
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.
If true, the element will grow to fill available space.
This prop works only if the element is a direct child of a Stack.
The ID referenced by the global component state.
Callback for when the form is submitted. The callback is passed the form's input state as input.
If true, the form input state will be reset to their initial values on submit.
slug
field.shownFields
is set, only fields in shownFields
are shown.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.Label on the form's submit button.
If true, the submit button is disabled and a spinner is shown. This is set automatically when using a task-backed form.
slug
field.shownFields
is set, only fields in shownFields
are shown.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. One of fn or slug is required.onSuccess
and onError
callbacks will run on task success or failure.refetchTasks
param. See refetchTasks on a mutation for more information.State API
Function to reset all of the form's inputs
Map of the form's input IDs to their values