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.

7 drag component

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.

8 edit component

The settings for a form component are different for each component type.

Textfield

A textfield 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.

9 textfield edit settings

Label

The name or title for this component.

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

See the jquery.inputmask documentation for more information.

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.

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. 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.

Table View

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

10 validation

Required

If checked, the field will be required to have a value upon submission.

Minimum length

The minimum number of characters required to be entered for this field.

Regular Expression Pattern

The regular expression pattern test that the field value must pass before the form can be submitted. See regex101.com for help with writing regex expressions.

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

Button

Buttons can be added to perform various actions within the form.

11 button

Label

This is the label or title that will appear on the button.

Action

This is the action that will be performed. Currently there are two actions that can be performed, submit and reset.

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.

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.

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.

Content

Content may be added to a form to provide non-field information. For example, if you need instructions at the top of a form that are for display only, use a Content component. There are no settings for a Content component and the value is not submitted back to the server.

A WYSIWYG editor has been provided to help with formatting the content. If you use the HTML view of the editor, note that all unsafe HTML is stripped before rendering to prevent cross-site scripting exploits. This includes tags like <script>, <embed>, and <style>, and attributes like onmouseover or onload.

Custom

Custom components allow creating a form field with a custom JSON schema that can be rendered as anything within a frontend application. This is usefully for special or complex form fields that don’t already exist in form.io. Using this type, any kind of field can be created.

To use a custom component, create a JSON definition of the field with the information needed to render it. Create a custom field and paste the JSON object into it. This must be a valid JSON object.

{
  "type": "custom",
  "isNew": true,
  "key": "custom",
  "protected": false,
  "persistent": true
}

There are several properties that are required but you may add any additional properties that you would like.

Type

The type property will be used to select which component to render on the frontend. It cannot be an existing field type.

Key

The key field is where the data will be saved to. This must be unique per field. For example, if key = 'customers' then the value of the field will be saved in data.customers.

Persistent

This will determine whether or not the value is saved to the main database. This is useful for using Remote Middleware, verify password fields or sending the data in an action but not saving it.

Protected

This will determine whether or not the field will be visible from the API. If it is a protected field then it will only be writeable but not readable.

Rendering

In order to render the custom component, the frontend application must register the component template. This is done in the config step with the formioComponentsProvider.

app.config([
  'formioComponentsProvider',
  function (formioComponentsProvider) {
    formioComponentsProvider.register('checkmatrix', {
      title: 'Check Matrix',
      template: 'formio/components/check-matrix.html',
      settings: {}
    });
	}
]);

The template will then be used to render the component. In addition, a controller may be added to the template to create more interactive form elements.

This is a working example of a custom component. It is a Matrix checkbox that changes the number of columns and rows based on two other form fields.

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.

File

A file field allows users to upload and download files to a form. In order to use a file field, file storage must be set up. This can be done from the project settings. See File Storage for the types of providers supported.

Form.io does not host any files itself. Files are stored on the storage provider which allows uploading and downloading files to and from it. Form.io only stores a reference to the files which allows seamless integration into your app.

12 s3

Label

The label for this field that will appear next to it.

Storage

This is the storage provider where the file will be stored and accessed from. Select the appropriate provider. All providers besides Url require additional configuration in project settings.

Upload Url

If Url is selected in Storage, enter the Url of the service. It must be compatible with the ng-file-upload service and return an object that includes the url to access the file.

Directory

This field will append all files with the string so that they are in a directory on the storage provider. Must end in “/”.

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 unchecked, only one file per field is allowed. If checked, multiple are allowed.

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 going to the submissions for a form.

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.

Image

Images within Form.io are created on the Form using the File component, which is capable of uploading images.

Displaying the images, however, is done within the implementation of the application retrieving the data. As an example, here is an Angular directive which illustrates how an image can be loaded within a <img> tag within your application dynamically from the file component on the form.

Hidden

A hidden field can be added to a form to create a resource property that can be custom set in the form. You can use javascript to set the value on the client side and when the form is submitted the value will be set on the resource. There is no front end widget for hidden fields.

13 hidden

Name

The name for a hidden field is not displayed on the client side and is used for administration purposes only. The name is used to generate the automatic property name but this can be changed on the API tab on the component settings modal.

Custom CSS Class

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

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. You can still see the value on form.io by going to the submissions for a form.

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.

HTML Element

An HTML Element component may be added to a form to display a single HTML element. This is useful if you wish to quickly insert and configure some HTML in your form. All unsafe HTML is stripped before rendering to prevent cross-site scripting exploits. This includes tags like <script>, <embed>, and <style>, and attributes like onmouseover or onload.

If you wish to insert more complicated HTML in your form, see the Content component

HTML Tag

The name of the HTML tag to display.

CSS Class

The CSS class to add to the HTML element. You may specify multiple classes by separating them with single spaces.

Attributes

Attributes and their values to add to the HTML element. This is commonly used to add href attributes to <a> tags, or src attributes to <img> tags.

Content

The text content of the HTML element. While adding more child HTML tags here will properly display them, it is recommended you use the Content component to easily write and preview more complex HTML.

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.

Radio

Radio form components should be used when presenting a list of options from which one should be chosen.

14 radio

Label

The label for this field that will appear next to it.

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.

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.

Inline Layout

If checked, this field will layout the radio buttons horizontally instead of vertically.

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 going to the submissions for a form.

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.

15 radio validation

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

Select

A select field will display a list of values in a drop down list to users. Users can select one of the values.

16 select

Label

The label for this field that will appear next to it.

Placeholder

The placeholder text that will appear before an option is selected.

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. 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 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 drop down with a list of all States within the U.S. You can use an external JSON array like the following.

https://cdn.rawgit.com/mshafrir/2646763/raw/states_titlecase.json

And place that within the URL of the select drop down Data Source URL. You will then 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 for this particular setup.

Select URL JSON Source

This will now turn your select dropdown into a list of available States within the US.

Value Property

If Raw JSON or URL is selected, enter the name of the property on the objects that will contain the value that will be stored in the database.

Search Query Name

If URL is selected, enter the name of the search query parameter to filter requests with. Example, if your url is http://api.dogs.com/dogs, and this option is set to type, and the 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

If Raw JSON or URL is selected, use the template field to determine how the values will be displayed in the select box. 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.

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.

Required

If checked, the field will be required to have a value.

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 typicaly usecase is a form that provides the Make, Model, and Year of automobiles where when you select the Make dropdown, it filters the Model dropdown for those that are within that Make. This functionality can be achieved using the following method. We will use the Make, Model, Year as an example use case for this docs.

Step 1: Create a Make Resource to hold all of the vehicle makes. Create Vehicle Resource

Step 2: Create some Vehicle make records. Create Vehicle Makes

Step 3: Create a Model Resource to hold all of the vehicle models. Create Vehicle Model

Step 4: Create some Vehicle model records. Create Vehicle Model

Step 5: Create the Vehicle Resource to hold all of the vehicles. Create Vehicle Resource

with the following settings for Make:

Data Resource Type: Resource Resources: Make Value: Make

Vehicle Make Settings

and the following settings for Model

Data Resource Type: Resource Resources: Model Value: Model Refresh on: Make

Input a Filter Query: data.make={{ data.make }}

Vehicle Model Settings

Step 6: Create a bunch of records within Vehicle resource. Create Vehicle Records

Step 7: Create a new form called Vehicle Select Vehicle Select Form

Step 8: Add the Make dropdown with the following field settings.

Data Resource Type: Resource Resources: Make Value: Make

Make Field

Step 9: Add the Model dropdown

Data Resource Type: Resource Resources: Model Value: Model Refresh on: Make

Input a Filter Query: data.make={{ data.make }}

Model Field

Step 10: Add the Year dropdown

Data Resource Type: Resource Resources: Vehicle Value: Year Refresh on: Model

Input a Filter Query: data.make={{ data.make }}&data.model={{ data.model }}

Year Field

You are done! Your form now will dyanamically filter based on what is selected.

Text Area

A textarea has the same options as the textfield form component. The difference is that it will be a multi-line input field that allows for longer text.

Creating a WYSIWYG Editor

The textarea component can also be used to create a WYSIWYG editor within your application using the famous CK Editor. This works by enabling a hidden wysiwyg flag on the textarea component. Currently, there is not a UI to make this change, so this will require you to use our API’s to make that change. Using Postman, we can first get the form we want to modify as follows.

You can then copy the Body of the form, change the URL to a PUT command, and then paste the body into the payload while changing that paramter to “true” like the following.

The next thing you will need to do is to add the following libraries to your front-end Angular.js application.

bower install --save ng-ckeditor

You will then need to add both CKEditor and the ng-CKEditor libraries to the page as follows.

<script src="//cdn.ckeditor.com/4.5.8/standard/ckeditor.js"></script>
<script src="./bower_components/ng-ckeditor/ng-ckeditor.js"></script>

And then initialize it within your Angular application as follows.

angular.module('myApplication', [
    'formio',
    'ngFormioHelper',
    'ngCkeditor'
  ])

Once you do this, your TextArea will show up as a WYSIWYG editor!

Address

The address form component is a special component that does lookups for addresses entered. It can be entered in free form and will save the address as well as geolocation and other information.

17 address

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.

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. You can still see the value on form.io by going to the submissions for a form.

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.

Check Box

A check box is a boolean value input field. It will either be on or off.

18 checkbox

Label

The label for this field that will appear next to it.

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. You can still see the value on form.io by going to the submissions for a form.

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.

19 checkbox validation

Required

If checked, the field will be required to be checked. 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.

Select Boxes

The Check Boxes form component works like the Radio component, but allows the user to check multiple values.

20 select box

Label

The label for this field that will appear next to it.

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.

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.

Inline Layout

If checked, this field will layout the checkboxes horizontally instead of vertically.

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 going to the submissions for a form.

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.

21 select box vali

Required

If checked, the field will be required to have at least one box checked. 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 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

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. You can still see the value on form.io by going to the submissions for a form.

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.

26 date time vali

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

Number

Number fields should be used whenever a field should be limited to a type of number.

26 number

Label

The label for this field that will appear next to it.

Placeholder

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

Increment (Step)

If set, the number field will be required to be an increment of this number. For example, if Increment is set to 5, possible values would be 0, 5, 10, 15, etc.

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.

Table View

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

27 number vali

Required

If checked, the field will be required to have a value.

Minumum Value

If a number is entered, then the value input on the form must be greater than or equal to this value.

Maximum Value

If a number is entered, then the value input on the form must be less than or equal to this 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

Curreny

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.

Phone Number

The phone number form component can be used to enter phone numbers in a form.

28 phone number

A textfield 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.

9 textfield edit settings

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

See the jquery.inputmask documentation for more information.

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. You can still see the value on form.io by going to the submissions for a form.

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.

29 phone vali

Required

If checked, the field will be required to have a value.

Resource

A resource field allows users to reference other resources in your project. For example, if you have a Director resource and a Movie resource, you can add a resource field on the Movie to reference the Director.

30 resource

Label

The label for this field that will appear next to it.

Placeholder

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

Resource

Select the type of resource to reference. This must be an existing resource within your project.

Search Expression

A regular expression to filter the results with. If you don’t want to show all possible resources within the Resource type selected in Resource you can limit which ones will appear in the options by enter a Regular Expression.

Select Fields

Select which properties on the resource to return as part of the options. Select whichever fields you want to display in the template.

Search Fields

A list of search filters based on the fields of the resource. See the Resource.js documentation for the format of these filters.

Item Template

How an item should appear in the list. Use {{}} brackets to reference variables to display. Be sure to use “Select Fields” above to select the fields to display.

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 Resources

If checked, more than one value will be allowed to be entered.

Table View

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

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

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

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.

31 api path

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.

layout

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

Caclulated values allow calculating values based on the values in other fields of the form. Calculated values uses 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.

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.