Links

Form Components

Learn about the Form Components and the settings available within the Form Components.
A Form component collects user data and serves as the display or user interface within the system. Form components define the type of widget that users will enter their data and will automatically add a property to the resource endpoint to interact with the Form component.

Adding a Form Component

To add a form component to a form, drag and drop the component from the left column into the desired location within the form.
Each new form starts with a submit button automatically added to it. This can be removed or edited as necessary.
Drag and drop a component from the left column to any place in the form

Editing a Form Component

To edit a form component on a form, hover over the component and click the gear icon. You will then be presented with a settings form for the component.
Click the Edit (gear) button to edit a form component
The settings for a form component are different for each component type.

General Settings

Below is a list of general settings that are offered for the majority of our components.
General Settings available for most components

Label

The name or title for this component.
Hide Label
Hide the label of this component. This setting will display the label in the form builder, but hide the label when the form is rendered.
Label Position
Position for the label for this field.
Label Width
The width of label on line in percentages.
Label Margin
The width of label margin on line in percentages.

Placeholder

The placeholder text that will appear when this field is empty.

Description

The Description is text that will appear below the input field.

Tooltip

Adds a tooltip icon to the side of this field.

Error Label

The label that will display for the field when a validation error message is shown.

Input Mask

An input mask helps the user with input by ensuring a predefined format. For a phone number field, the input mask defaults to (999) 999-9999.
  • 9: numeric
  • a: alphabetical
  • *: alphanumeric
Allow Multiple masks
This setting will allow you to set multiple input masks for the field. The mask is selected by the user via a dropdown list and will dynamically switch the mask for the field when selected. This feature is only availabe on our formio.js renderer.

Prefix

The text to show before a field. An example is ‘$’ for money

Suffix

The text to show after a field. An example would be ‘lbs’ for weight.

Custom CSS Class

A custom CSS class to add to this component. You may add multiple class names separated by a space.

Tab Index

Sets the tabindex attribute of this component to override the tab order of the form. See the MDN documentation on tabindex for more information on how it works.

Multiple Values

If checked, multiple values can be added in this field. The values will appear as an array in the API and an “Add Another” button will be visible on the field allowing the creation of additional fields for this component.

Enable Spell Check

This setting will enable spell check on the field.

Protected

If checked, this field is for input only. When being queried by the API it will not appear in the properties. You can still see the value on form.io by viewing the form submissions.

Persistent

If checked, the field will be stored in the database. If you want a field to not save, uncheck this box. This is useful for fields like password validation that shouldn’t save.

Field Level Encryption

Set on a per-field basis, this setting allows encryption of specified fields within a form that may contain sensitive information. This setting limits access to the submission data requiring the use of APIs to access data while maintaining full database encryption.
Field Level Encryption is two-way encryption and should not be used for Passwords
This setting can be found in the Data tab of the component settings.
This setting is included in the Security and Compliance package. Follow the link or contact [email protected] for more information.

Hidden

A hidden field is still a part of the form JSON, but is hidden when viewing the form is rendererd.

Initial Focus

Make this field the initially focused element of the form when rendered. We recommend configuring this setting only once on your form. If more than one component on the form has the Initial Focus setting checked, only the last component in the JSON structure with the setting enabled will be focused on the form.

Hide Input

Hide the input when viewing the form from the front end browser. This does not encrypt on the server. Do not use for passwords.

Disabled

Disable this field on the form.

Show Label in DataGrid

Show the label of this component when in a datagrid.

Table View

If checked, this value will show up in the table view of the submissions list.

Basic Components

Text Field

A Text Field can be used for short and general text input. There are options to define input masks and validations, allowing users to mold information into desired formats.
Widget: You can change widget. The widget is the display UI used to input the value of the field.

Text Area

A Text Area has the same options as the Text Field form component. The difference is that it will be a multi-line input field that allows for longer text. The Text Area can also be utilized as ACE, CKEditor or Quill WYSIWYG editor for the end user which is configured within the component settings.
Rows: This allows control over how many rows are visible in the Text Area.
Editor: This option will turn the text area into the WYSIWYG Editor user interface of your choice.
Editor Settings: Here you can modify the code base of the WYSIWYG Editor to customize the UI specific to your needs.

Number

Number fields can be used whenever a field should be limited to a type of number value. There are options to set Thousands Separator, set Decimal Places and Require Decimals.
Use Thousands Separator: Check this setting if you would like the value in this component to separate thousands by a local delimiter.
Decimal Places: The maximum number of decimal places for the values in this field.
Require Decimals: Always show decimals for this field, even if trailing zeros.
Decimal Symbol: Change the default Decimal Symbol for the Number component.
This is a hidden setting that can be configured by editing the Number component JSON. Add the following to the schema:
"decimalSymbol": ","
The Number component Schema should look something like this:
After saving your changes, the Number component will change the default decimal to the designated symbol. Use this in conjunction with the local delimiter to achieve different kinds of numbering systems.

Password

The password field has the same options as a text field component. It differs from a text field in that its html <input> type will be password instead of text. This will cause the field to display asterisks instead of the value entered.

Check Box

A check box can be used for boolean value input field. It can either be on or off. There are options to set Shortcut and Input Type.
Shortcut: Shortcut can be added to check/uncheck checkbox.
Input Type: Input type can be changed to checkbox or radio.

Select Boxes

The Select Boxes allows the user to check multiple values from list of options.
Values: These are the values that will be selected on this field. The Value column is what will be stored in the database and the Label is what is shown to the users.
Inline Layout: If checked, this field will layout the checkboxes horizontally instead of vertically.

Select

The Select displays a list of values in a dropdown list to users. Users can select one of the values.
Widget Type: You can select the type of widget you would like to use.
Data Source Type: Select the type of data the options will be pulled from.
Values: These are the values that will be selected on this field. You should fill Data Source Values. The Value column is what will be stored in the database and the Label is what is shown to the users.
Raw JSON: Enter a JSON Array into Data Source Raw JSON to use. It should be formatted as an array of objects with named properties.
URL: Enter a url with a data source in JSON Array format. This can be used to populate a Select list with external JSON values. For example, suppose you wish to populate your Select dropdown with a list of all States of the U.S. You can use an external JSON array like the following.
https://cdn.rawgit.com/mshafrir/2646763/raw/states_titlecase.json
Place that in Data Source URL. Then you will need to provide the Value Property as well as change the Item Template so that it will pull the right value as well as display correctly within the dropdown. The following image shows how the configuration would look like for this particular setup.
This will now turn your select dropdown into a list of available States of the U.S.
Value Property: If Raw JSON, URL or Custom is selected as Data Source Type, enter the name of the property for the objects that will contain the value that will be stored in the database. If it is not specified, the item itself will be used.
Search Query Name: If URL or Resourse is selected as Data Source Type, enter the name of the search query parameter to filter requests with. Example, if your url is http://api.dogs.com/dogs, and Search Query Name is set to type, and then user types nice in the Select field, then this component will send a request to http://api.dogs.com/dogs?type=nice and update the Select items with the results. If this option is omitted, no new requests will be made when user enters text in the select field.
Item Template: Use the template field to determine how the values will be displayed in the Select dropdown. You can use the item variable to access the current object in the array. For example, you can embed the value by using {{ item.value }} in a template.
Dynamic Select Filtering
A very common use case that many people have in forms is to dynamically filter a Select dropdown based on the selection of another Select dropdown. The most typical use case is a form that provides the Make, Model and Year of vehicles where when you select the Make dropdown, it filters the Model dropdown for those that are inside that Make. This functionality is covered in detail in our user guide resources section.

Radio

The Radio allows the user to check only one value from list of options.
Values: These are the values that will be selected on this field. The Value column is what will be stored in the database and the Label is what is shown to the users.
Inline Layout: If checked, this field will layout the radio buttons horizontally instead of vertically.

Button

Buttons can be added to perform various actions within the form.
Action: This is the action that will be performed. Currently there are the next actions that can be performed - Submit, Save in State, Event, Custom, Reset, OAuth and POST to URL.
Submit: A submit action submits the form to either the form.io server or a custom callback url that has been priorly set up.
Reset: Reset the form fields back to their original state.
OAuth: Opens an OAuth authentication popup. This will only work after it has been assigned to an OAuth Action. See the OAuth guide for more information on how to set up OAuth in your project.
Theme: Set a theme (color) for the button. These options currently map to Bootstrap classes that will be added to the button.
Size: Set the size of the button. These options currently map to Bootstrap classes that will be added to the button.
Left Icon: If you have an icon library and would like to include an icon to the left of the button label, you can do so by adding the icon class here.
Right Icon: If you have an icon library and would like to include an icon to the right of the button label, you can do so by adding the icon class here.
Block: If checked, the display of the button will be set to “block” which will cause it to span the full width of the container.
Disable on Form Invalid: If checked, this button will be disabled if any of the client side validation fails. This is useful for preventing the submission of a form that has invalid data entered.

Advanced Components

Email

The email component is nearly identical to the text field component. The Email component has a custom validation setting that, if set up correctly, can ensure the value entered is a valid email address. The email component can also more easily be integrate into a form’s email action. Use this component when you want an email address field for your form.
Realtime Email Validation using Kickbox.io
In addition to the normal email format validation, we are excited to bring real-time Email validation through our integration with Kickbox.io. For more information on how this works, please checkout the Kickbox Integration section.

URL

The URL component is nearly identical to the text field component. The URL component has a custom validation setting that, if set up correctly, can ensure the value entered is a valid url.

Phone Number

The phone number form component can be used to enter phone numbers in a form.
28 phone number
A Text Field can be used for general text input that is shorter than a sentence. There are options to define input masks and validations so information can be molded into desired formats. Click here to learn more about Input Masks
Label: The label for this field that will appear next to it.
Placeholder: The placeholder text that will appear when this field is empty.
Input Mask: An input mask helps the user with input by ensuring a predefined format. For a phone number field, the input mask defaults to (999) 999-9999.
  • 9: numeric
  • a: alphabetical
  • *: alphanumeric
Example telephone mask: (999) 999-9999
Prefix
The text to show before a field. An example is ‘$’ for money
Suffix
The text to show after a field. An example would be ‘lbs’ for weight.
Custom CSS Class
A custom CSS class to add to this component. You may add multiple class names separated by a space.
Tab Index
Sets the tabindex attribute of this component to override the tab order of the form. See the MDN documentation on tabindex for more information on how it works.
Multiple Values
If checked, multiple values can be added in this field. The values will appear as an array in the API and an “Add Another” button will be visible on the field.
Unique
If checked, this field will be enforced as unique for this form. Submissions will be checked to see if an existing value matches. This validation is currently server side only.
Protected
If checked, this field is for input only. When being queried by the API it will not appear in the properties and also should not appear in exported data. You won’t be able to see the value on form.io, but it will be stored in database under the hood.
Persistent
If checked, the field will be stored in the database. If you want a field to not save, uncheck this box. This is useful for fields like password validation that shouldn’t save.
Table View
If checked, this value will show up in the table view of the submissions list.
Required
If checked, the field will be required to have a value.

Tags

Multiple or single tags can be used to categorize items. Use the tag component when it’s useful for the user.

Address

The Address component is a special component that performs an address lookup based on user input using several map and location providers. Address data can also be entered in free form and will save the address as well as geolocation and other information.
17 address
Google Maps API Key
Due to recent changes to the Google Geocode API usage policies, this is now required for all Address components. To setup an API key, you must follow the following directions.
Due to recent changes to the Google Maps API usage policies, an enabled Maps Javascript API and valid Maps API Key are required for all Address lookups using the Google Maps provider. Follow the instructions below to generate your Google Map API key.
Navigate to the Google Maps Platform and click the Get Started button
Follow the steps and Google will create a Project and Maps API key. Copy the API key and ensure you check the 'Enable all Google Maps API's for this project' setting
If you've never used the Google Cloud Platform before, follow the steps below to generate an API key.
Navigate to the Google Maps Platform and click the ' Enabled API's and services' tab to view enabled API's (ensure the Maps Javascript API is included in the 'API's and services' section)
Click the Credential tab to review or copy your Map API key if you did not do so in the previous step
It's advised to restrict your API key to prevent unauthorized usage. Edit your API key to add restriction parameters
Login to Form.io and add an Address component to a form
Inside the Address settings, click the Provider tab, select Google Maps, and paste your Google Maps API key
Use the form and the Address component will perform a lookup and populate results as the user inputs data into the field
Label: The label for this field that will appear next to it.
Placeholder: The placeholder text that will appear when this field is empty.
Custom CSS Class: A custom CSS class to add to this component. You may add multiple class names separated by a space.
Tab Index: Sets the tabindex attribute of this component to override the tab order of the form. See the MDN documentation on tabindex for more information on how it works.
Allow Multiple Addresses: Allow multiple addresses to be entered into the field.
Your new project's dashboard
The APIs and Services menu
The Credentials menu
A newly created API Key
  • For production environments, it's recommended that you restrict this API key to the services you'll need. If your API key will be used solely with the Form.io advanced Address component, you should consider restricting your API key to only the Places API and the Maps Javascript API (please note that those APIs must already be enabled from the "Enabled APIs and Services" page.
  • In the Form.io Address component menu - under the Provider tab - paste your active Google Cloud project's API key in the field labeled "API Key." Make sure you've chosen "Google Maps" in the select box labeled "Provider."
  • Now that you have a project created, you can then setup Billing for that project by clicking on Set Account on the billing modal. If you selected an existing project, you will not see this page.
  • If you created a new project, you will then need to provide a payment mechanism so that Google can charge for your usage of their GeoCode API.
  • On the next modal, you will then click Next to enable the Mapping API’s needed for the Address compoennt.
  • The next modal will then show you the API Key that you need to use for this field in the Address component.
Unique: If checked, this field will be enforced as unique for this form. Submissions will be checked to see if an existing value matches. This validation is currently server side only.
Protected: If checked, this field is for input only. When being queried by the API it will not appear in the properties and also should not appear in exported data. You won’t be able to see the value on form.io, but it will be stored in database under the hood.
Persistent: If checked, the field will be stored in the database. If you want a field to not save, uncheck this box. This is useful for fields like password validation that shouldn’t save.
Table View: If checked, this value will show up in the table view of the submissions list.
Required: If checked, the field will be required to have a value.

Date/Time

Date/Time form components can be used to input dates, times or both dates and times.
22 date time
Label: The label for this field that will appear next to it.
Default value: The default value for the date component. You can put new Date(); for the current date or use a few of Moment.js functions to set the date to a specific date. For example: moment().add(50, 'days').calendar(); You can use the add or subtract function to go forward or backwards in dates.
Placeholder: The placeholder text that will appear when this field is empty.
Date Format: The format for displaying this field’s date. The format must be specified like the AngularJS date filter.
Custom CSS Class: A custom CSS class to add to this component. You may add multiple class names separated by a space.
Tab Index: Sets the tabindex attribute of this component to override the tab order of the form. See the MDN documentation on tabindex for more information on how it works.
Protected: If checked, this field is for input only. When being queried by the API it will not appear in the properties and also should not appear in exported data. You won’t be able to see the value on form.io, but it will be stored in database under the hood.
Persistent: If checked, the field will be stored in the database. If you want a field to not save, uncheck this box. This is useful for fields like password validation that shouldn’t save.
Table View: If checked, this value will show up in the table view of the submissions list.
23 date
Enable Date Input: If this is checked, dates can be entered for this field.
Initial Mode: When the date picker appears, this sets the initial view of the picker.
Minimum Date: A value of the date that this field’s value must be after.
Maximum Date: A value of the date that this field’s value must be before.
Starting Day: On the calendar, select the day of the week that should start the week. In Europe this is typically Monday and in the US this is typically Sunday.
Minimum Mode: Limit the datepicker modes to a minimum of this value.
Maximum Mode: Limit the datepicker modes to a maximum of this value.
Maximum Years Displayed: The maximum number of years to display in the datepicker.
Show Week Numbers: If this is checked, when in Day mode, the datepicker will display the week number on the left hand side of the datepicker.
24 time
Enable Time Input: Allow entering a time as part of this field.
Hour Step Size: The number of hours to increment/decrement in the time picker.
Minute Step Size: The number of minutes to increment/decrement in the time picker.
12 Hour Time (AM/PM): If checked, time will be displayed in 12 hour (am/pm) time. If not checked, it will appear in 24 hour time.
Read Only Input: If checked, users cannot directly enter a time. They can only use the increment/decrement controls to change the time. If unchecked, users can directly enter time values.
Required: If checked, the field will be required to have a value.
Custom Validation: You can use javascript to perform validation on a field. The way to respond is by setting the valid variable. If it is set to true then the validation passes. If you set it to a string, the validation fails and the validation message is set to whatever the valid variable is set to.
In addition, input variable is set to the value that has been entered in the field. The component variable is set to the definition of the field.
You can also reference other resources and properties for validation. For example, if there is a user resource with a password field, you can use its value with user.password

Day

The Day component can be used to enter values for the Day, Month, and Year using a number or select type of field.
Type of input: Type of input for Month, Day and Year can be selected between Number or Select type on Day, Month and Year tabs.
Hide Input Labels: The labels of component Month, Day, Year inputs can be hidden on the form.
Day first: The order of the fields can be changed. The Day field can be displayed before the Month field, if Day first is checked on the Day tab.
Minimum Year: A value of the year that this field’s value must be or after.
Maximum Year: A value of the year that this field’s value must be or before.

Time

The Time component can be used to input time using different time widgets you would like to use.
Input Type: The type of Time widget can be selected between HTML5 Time Input and Text Input with Mask.

Currency

The Currency component should be used when a field should display currency amounts on a form. This component holds a numeric input mask that allows two decimal values and automatically adds commas as a user inputs a currency amount.
currency
Label
The name or title for this component.
Placeholder
The placeholder text that will appear when this field is empty.
Prefix
The text to show before a field. An example is ‘$’ for money
Suffix
The text to show after a field. An example would be ‘lbs’ for weight.
Custom CSS Class
A custom CSS class to add to this component. You may add multiple class names separated by a space.
Tab Index
Sets the tabindex attribute of this component to override the tab order of the form. See the MDN documentation on tabindex for more information on how it works.
Multiple Values
If checked, multiple values can be added in this field. The values will appear as an array in the API and an “Add Another” button will be visible on the field allowing the creation of additional fields for this component.
Table View
If checked, this value will show up in the table view of the submissions list.

Survey

The Survey component works similar to the radio. Instead of one question, users are able to select a value for multiple questions which are configured within the component settings. Survey is a great component to utilize when asking multiple questions with the same context of answers or values.
Label
The label for this component that will appear next to it.
Questions
The questions you would like to ask within the survey.
Values
The values that can be selected per question. Example: ‘Satisfied’, ‘Very Satisfied’, etc.
Custom CSS Class
A custom CSS class to add to this component. You may add multiple class names separated by a space.
Tab Index
Sets the tabindex attribute of this component to override the tab order of the form. See the MDN documentation on tabindex for more information on how it works.
Protected
If checked, this field is for input only. When being queried by the API it will not appear in the properties and also should not appear in exported data. You won’t be able to see the value on form.io, but it will be stored in database under the hood.
Persistent
If checked, the field will be stored in the database. If you want a field to not save, uncheck this box. This is useful for fields like password validation that shouldn’t save.
Table View
If checked, this value will show up in the table view of the submissions list.
Required
If checked, the field will be required to have every question answered. If it is required, you may not need to persist the value as it can be assumed to be checked when a form was submitted or it will not submit.
Custom Validation
You can use javascript to perform validation on a field. The way to respond is by setting the valid variable. If it is set to true then the validation passes. If you set it to a string, the validation fails and the validation message is set to whatever the valid variable is set to. In addition, input variable are set to the value that has been entered in the field. The component variable is set to the definition of the field.

Signature

A signature field is a special field that allows someone to sign the field with either their finger on a touch enabled device or with the mouse pointer. This signature will be converted into an image and stored with the form submission.
31 signature
Footer Label
You can enter a short instruction here.
Width
How wide the signature area should be. This can be in pixels or percents.
Height
How high the signature area should be. This can be in pixels or percents.
Background Color
The Background color of the signature area. This can be an RGB value in RGB(255,255,255) format, a hex value like #000000 or the name of a color.
Pen Color
The pen color in the signature area. This can be an RGB value in RGB(255,255,255) format, a hex value like #000000 or the name of a color.
Custom CSS Class
A custom CSS class to add to this component. You may add multiple class names separated by a space.
Table View
If checked, this value will show up in the table view of the submissions list.

Component API

Property Name
Form components directly translate to a resource property on the API that is generated for the form. By default a property name is generated by camel casing the field title. You can change the property name by going to the API tab in the form component settings.
Field Tags
Tag the field for use in custom logic or within your application.
Custom Properties
This allows you to configure any custom properties for this component by setting a ‘Key’ and ‘Value’ for the property.

Component Layout Settings

In addition to Layout Components, which are detailed in the next section of this guide, you can marginally change the arrangement of the components on your Form within the Layout settings. Each component allows for marginal layout changes from top, bottom, left, and right.
To change the layout, simply input a margin amount in the Top, Right, Bottom, or Left field. Components will be arranged accordingly depending on what margin field you input to. Set margins must be a valid CSS measurement input like “10px” in order to render properly.

Conditional Components

The conditional component requires an API key to be configured to function correctly.
Any form component can use conditional logic to determine when to hide or display itself. The settings for a conditional field, are configured on the component itself, and can be found by viewing the Conditional tab within the components settings.
The conditional logic is based on the following rules:
  • Each field can hide or display.
  • The visibility is dependent on another component defined within the form.
  • The logic is activated when the configured field contains the plaintext value defined in the settings.
In addition to Simple Conditional logic, you can also use Advanced Conditional logic, which uses actual JavaScript for any combination of conditions.
JavaScript conditional logic requires you to set the value of show to either true or false. You have access to the current value of any form component via the data object, and the components API key. Advanced Conditional logic will only work, if Simple Conditional logic isn’t already defined.
When using Advanced Conditional logic with the select boxes form component, you must use the following syntax to get the value of the select box, which will always be true or false, depending on if it is checked or not: data.selectbox_component.selectbox_value

Calculated Value

Calculated values allow calculating values based on the values in other fields of the form. Calculated values use plain javascript and can return any value to the field. There are two variables available to calculate off of, data and row. data is the full data in the form. You can access values within it by using the field keys. For example data.myfieldkey. If you field is within a datagrid, there is an additional variable available of row which contains the values for that row of the datagrid. You can access the values the same as with data as row.myfieldkey. The values are also in data.mydatagrid[0].myfieldkey and data.mydatagrid[1].myfieldkey plus each additional row as the index.
Also you have access to special util variable - library of useful functions. More information about util library can be found here.
Return the calculated value in the value variable and it will be set. Each time the form values change it will be recalculated. You do NOT need to watch form fields as you do for other custom logic in your form. It will automatically update.
It is very common to disable the field using calculated values.