Submit a form to perform actions with input data. The form component provides a way for users to view and manipulate multiple data fields with their inputs, and are a key part of many tools. Upon submission, forms perform functions like creating (inserting) a new data record, updating an existing record or calling APIs.
Use a form if you expect the user to interact with multiple data fields for the form's function. If you need a user to enter in an email and customer name, select an item from a dropdown, and then write a paragraph of text, forms are your best option. This is usually the best component when your function is to create entirely new data records.
Sometimes you may have a process where a user needs to view data fields and confirm that it's correct, or make adjustments if needed. Since form fields can display pre-filled data, you can have every field populated with data, allowing the user to view change any values that they need to.
Want the benefits of a form but without sacrificing real estate in your design? Try a Pop-up Form.
First, select the function that this form should perform when it is submitted.
For most databases, you'll see auto-generated insert, update, and delete functions. For example, if you selected your PostgreSQL database with a Users table, you'll see "insert Users record", "update Users record", and "delete Users record" functions appear.
For most business apps, auto-generated functions will appear, based on the available APIs of that app. For an app like Stripe, you'll see functions for "insert Balance Transactions record", "update Balance Transactions record", "delete Balance Transactions record", and so forth based on what's available in Stripe's API.
Here, you can edit the name of your form, the button text and also add additional instructions to be displayed on your form.
Here you'll determine the actual values that are passed along when the form is submitted. To do this, you’ll select fields, and then specify what values go in them.
By default, only required fields are added. For example, If you’re updating a record in a database, this would just be the primary key. Click “+” to view a list of all available fields for your selected function.
You’ll need to choose a value that is passed in for each field. Click the field to bring up options. You can let the user type in a value, get this value from an existing component, set a custom default value, set a UUID, set to null, or set to the date-time the form is submitted (date/time fields only).
Let's walk through a commonly used setup where we get the form values from a table component. In this case, we want to build a form that will update an Orders record. To make it easier to use, we also want to pre-fill the form fields with existing data.
The best way to set this up is to first add a table with your Orders data, which will then provide data to your form.
Then, add a form component to your space, with "Update Orders record" as its function. Go to the "Fields" section and add all the form fields you want the user to see and update. Click on each field, specifying that the value comes from that same field in the Orders table. Ie, for “Quantity”, choose to get the value from a component, then select the Orders table -> Selected Row -> Data -> Quantity.
Then save and publish your space. You'll see that clicking on a row in the Orders table will prefill those values in the Update Order form (these two components are now "bound" together).
Check out Field Configuration to learn about all the options for specifying values.
Forms are great when you want users to view and potentially edit data fields. However, there are certain data fields where it is unnecessary for a user to view or alter before submitting. For these, you can use a hidden field, where data is still submitted but the field isn't shown to users of your form. Click the eye icon to make any field a hidden field.
You can create visibility rules that will determine when this component is visible and able to be interacted with.
Usually, if your form submission changes some data that is displayed in the Space, you'll want to update what's displayed. On Submit options allow you to refresh the data of a component in the Space.
You can uncheck Reset form input values after submitting if you don't want to clear values when the form is submitted. Note that if you have pre-filled default values (coming from another component, generated UUID, etc), those values do not clear (simply reset) even if this is checked.