Component Settings

Configuration options for the components

Before learning about the various components Form.io provides, it's important to first understand the settings behind these components. While many components offer unique settings specific to the component type, there are many settings that span across the majority of components. Below is a list of these settings organized by setting type.

Display

Settings that visually change field elements

Data

Settings related to how field data is set or interacted with from the Back-End

Validation

Settings to configure Front-End and Back-End validations on the field

API

Configures the API endpoint for the field as well as Custom Properties

Conditional & Logic

Set up basic conditional workflows or advanced logic

Layout

Configure HTML properties and PDF overlay positions

Click the Hide Preview button in the component settings to expand the options and conceal the field within the settings module.

Display Settings

Settings that modify the front-end UI of a component. The Display setting tab will open by default when editing the component settings.

Label

The front-end name for the component. By default, the label will display at the top left of the field.

Label Position

The label location of the component. The Lable Position will default to the Top option, but several other options can be selected:

• Top - The Label will display left aligned on the top of the component

• Left (Left-aligned) - The Label will display to the left of the component and aligned to the left of the component width span.

• Left (Right-aligned) - The Label will display to the left of the component and aligned to the right of the component width span.

• Right (Left-aligned) - The Label will display to the right of the component and aligned to the left of the component width span.

• Right (Right-aligned) - The Label will display to the right of the component and aligned to the left of the component width span.

• Bottom - The Label will display left-aligned below the component

Label Width & Margin

When the Left or Right Label Position alignment options are selected, the label width and margin settings will become available. These options allow for padding to be added to the respective position of the component which will create space space between the label and the component. The width and margin values are based on the field's span percentage on the form.

Use the label position when formatting your form in a grid-like fashion or to save vertical space on your form.

Placeholder

A short descriptive text that describes the expected value that the user should enter in the field. The Placeholder will display when the field is empty and will not be submitted to the server when the form is submitted.

Use the Placeholder as helper text for users filling out the field.

Description

Add a Description that will display below the field. This setting can be used as an alternative to the Placeholder or in addition if further details are needed for the field.

Use HTML in the setting field to style the content of the Description

Tooltip

Adding content to the Tooltip setting will add a new UI element to the field represented by a question icon next to the field label. The content inside the Tooltip setting will display when a user hovers over the UI element. Tooltips are a great way of providing detailed instructions or helper tips without taking up space on your form.

Use HTML in the Tooltip setting field to style the content inside the Tooltip.

Prefix

The Prefix setting adds text or characters before the input field. This can be used to categorize or label a field, like using $ for currency.

Suffix

The Suffix setting adds text or characters after the input field. This can be used to categorize or label a field, like using % to represent a percentage.

Custom CSS Class

Apply unique styling and formatting to your fields by adding Custom CSS Classes. Form.io utilizes Bootstrap as the default CSS framework for the renderer. Below are examples showcasing a few different Custom CSS Classes you may find useful and the class code.

Field Background, Text Color - bg-info text-white

Alerts, Padding - alert-success p-3

Reposition Fields - float-right , float-left

Visit the Bootstrap Documentation site for a full list of customizable classes and tags you can apply to your fields and form.

Tab Index

Configure the Tab Index attribute of this component to override the tab order of the form. Setting the tab order for all components on the form gives you control over the entire tab order of the form.

See the MDN documentation for more tab index information.

Auto Complete

Enabled by default, input fields will automatically populate data from values previously entered by the user dictated by the cache of the user's browser. Input the off value inside the setting field to disable.

See the MDN documentation autocomplete documentation for more information.

Hidden

Hidden components do not display on the form but are still part of the form JSON and submission. This setting can be helpful when calculating data that should not be visible to the front-end user

Hide Label

Hides the label of a field. Save vertical space on a form by hiding the field label and utilizing other display settings such as a Placeholder to identify the field.

Hide Input

Masks the input of the field by replacing characters with circle characters often seen on password fields. Use this setting when handling sensitive data such as a Tax ID or Social Security Number.

Hide Input does not encrypt the data on the server. Do not use this setting for Passwords.

Initial Focus

When the form is rendered, the component with Initial Focused checked will be the focused element on the form.

Only one component on the form should have the Initial Focus setting enabled. 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.

Disabled

The Disabled setting will prevent users from focussing and inputting data into the field. Use Disabled fields in conjunction with Calculated Values to prevent a user from altering calculations or populated values.

Disabled fields will always display in gray

Table View

When the Table View setting is checked, the field and underlying data will display within the Submission Data Grid of the form. "Data is always saved on the server, whether or not the setting is enabled.

Adjust the Table View settings for each component in your form to streamline the submission grid in the Form's Data tab, ensuring that the most relevant data is displayed when reviewing submissions.

Modal Edit

When this setting is enabled, the field is replaced with a button, that when clicked, launches a Modal Window to input and edit field data.

UI of the Modal Edit window when a field with this setting is selected

Enable this setting for a layout component to contain a multitude of fields inside a single modal window.

Data Settings

Data settings are primarily utilized for configuring end-user input data, determining how it interacts with other field data within the form, and how it is stored on the server. Use Data Settings to perform tasks such as setting a default value or configuring data calculations.

Multiple Value

The Multiple Value setting introduces an Add Another button below the field and allows the user to add or remove multiple rows of a component. Data is saved as an array within the submission.

Default Value

Sets the default input value for the field which will display in the field when the form is rendered. If left unchanged, the default value data will be saved with the submission.

Persistent

This setting will determine how the field data will be stored. Below are the following options for the Persistent setting. The default setting is set to Server:

Server: The Front-End WILL submit the data to the backend, and the backend WILL store the value

Client-only: The Front-End WILL NOT submit the data to the backend, and the backend WILL NOT store the value.

This can be beneficial when the server needs to intercept data for workflows such as logic or calculations, but there is no need or desire for the data to be stored.

None: The Front-End WILL submit the data to the backend, but the backend WILL NOT store the value.

Use this setting if client-side logic is needed on the form without the requirement of sending or saving the data to the server.

Protected

This setting will prevent the field data from being queried from an API call. Check this setting if an extra layer of protection is needed for sensitive data.

Database Index

Index the field within the database to increase server-side performance when querying submissions.

Truncate Multiple Spaces

Removes any unnecessary spaces between words or characters within the field.

Encrypted

Adds a server-side Encryption layer to the field. This is a two-way encryption not suitable for passwords. Form.io ensures the security of sensitive data through a multi-layered approach to encryption. At the foundational level, Form.io runs on MongoDB, and when using MongoDB Atlas, encryption at rest and in transit is provided by default, using advanced encryption standards to ensure that all data is protected at multiple layers. Building on this foundation, Form.io adds an additional layer of security through its encrypted fields functionality. This process leverages the robust aes-256-cbc algorithm, a symmetric encryption method known for its high level of security. To perform the encryption and decryption, Form.io utilizes the OpenSSL library via Node.js. Leveraging OpenSSL allows Form.io to securely encrypt data before storing it and decrypt it when necessary, ensuring that sensitive information remains protected throughout its lifecycle. The use of aes-256-cbc ensures that data is encrypted with a 256-bit key, providing a strong defense against unauthorized access.

This setting is included in the Security Module. Follow the link or contact [e-mail] for more information.

Redraw On

Refresh the component when a specific change occurs. The Redraw setting dropdown will offer options to redraw the component when any change occurs on the form or when a specific field on the form changes selectable within the setting dropdown. Use this setting when interpolating data for calculations or logic when dynamic changes occur form.

Use this setting when interpolating data on the form or setting up Dynamic Select Filtering workflows.

Omit Value From Submission Data When Conditionally Hidden

As of API Server version 9.4.0, the Clear Value When Hidden setting has been renamed to Omit Value From Submission Data When Conditionally Hidden. Please see the details below for changes to the setting's behavior.

This setting determines the behavior of a field's value when the field becomes conditionally hidden on the form. By default, this setting is enabled, meaning the field value is cleared if the field is hidden. This is the expected behavior when conditionally showing or hiding components.

When the "Omit Data When Conditionally Hidden" functionality is disabled, a field's data will not be included in the submission if it is hidden using conditional logic. However, fields hidden through the Hidden setting in the component's Display tab will retain their data in the submission, even if this property is enabled.

To retain the value of a conditionally hidden field and have it reappear when the field is shown, disable this setting.

Example Scenarios:

1. Single Component: A text field hidden via a conditional logic rule with "Omit Data When Conditionally Hidden" enabled will exclude its value from the submission.

2. Container/Group: A group of fields inside a container hidden via conditional logic will omit all data from the container if "Omit Data When Conditionally Hidden" is enabled. e.g fields inside a conditionally hidden Panel

3. Display Tab Hidden: A field hidden using the Hidden setting found within the component the Display tab will retain its value in the submission, even when this property is enabled.

Custom Default Value

Expand the Custom Default Value tab and write custom Javascript or JSON Logic to set the field's default value.

Calculated Value

Expand the Custom Default Value tab and write custom Javascript or JSON logic to set up calculation logic on the field. This section allows you to write custom JavaScript snippets that will be evaluated to perform advanced calculations within your component.

The way that this works is that it will execute your snippet of JavaScript within an evaluation sandbox, which includes a number of variables (included below). The result of the calculation will then be set on a special variable called the "return" variable. In the case of Calculated Values, the name of this variable is called "value". It should be noted that the name of the "return" variable is different depending on if you execute a Calculated Value, Custom Conditional, as well as Logic Triggers and Actions. For example, let's suppose that you have a form with 2 number components A and B. You then drag and drop another component, called Sum onto the form. You can automatically set the value of the Sum component by providing the following in the Calculated Value section.

value = data.a + data.b;

In this example, we use the 'data' context variable to capture the values of Component A and B, and then assign the result of the calculation to the 'return' variable 'value.' During the evaluation, several variables are accessible for code execution. These variables make up the Evaluation Context which are detailed below:

Evaluation Context Variables

Variable Name	Description	Example
data	The "root" data object for the subission.	{ "firstName": "Joe", "lastName": "Smith", "email": "[e-mail]", "children": [ {"name": "Joey"} {"name": "Sally"} ] }
row	The contextual "row" data for any component that may reside within an Array based component that has multiple rows. For example, a Textfield within a Data Grid component may have multiple rows, and each row would have a different "row" context.	{"name": "Joey"}
input	FOR VALIDATION ONLY: The input value that was entered into the component to be validated	"hello"
rowIndex	The number of what row the component is currently within (if applicable)	2
form	The JSON of the full form definition	{ "_id": "...", "title": "Customers", "name": "customers", "path": "customers", "components": [...] }
submission	The full JSON object for the submission of a form	{ _id: "...", created: "...", modified: "...", deleted: null, data: {...}, metadata: {...} }
component	The JSON for the current component	{ "type": "textfield", "label": "First Name", "key": "firstName", "input": true }
options	The global options passed to the renderer.	{ "pdf": true, "readOnly": true }
t	The translation function used to dynamically translate strings within your evaluation context.	value = t('hello')
iconClass	A function that is able to dynamically swap out the iconset classes based on different templates that are loaded.	iconClass('home')
_	A subset instance of Lodash for providing helper functions to your evaluations.	value = _.get(data, 'customer.firstName');
utils	An instance of the Form Utils class. See https://github.com/formio/core/blob/master/src/utils/formUtil.ts	var comp = utils.getComponent(form.components, 'firstName');
user	The JSON of the currently authenticated user submission.	{ _id: "...", data: { email: "[e-mail]" } }
moment	An instance of the "moment" library, or in later renderer versions, an instance of Day.js library to use for data manipulation	value = moment('2022-01-33');
token	The current JWT token for the authenticated user.	---- A JWT TOKEN ---
config	The current form configuration, or the Project Public configurations object	value = config.baseUrl;
instance	The current component instance. CAUTION: Only used approved instance methods when using "instance" within your evaluations. See below for the list of approved instance methods that can be used.	value = instance.root.getComponent('firstName').getValue();

Return Evaluation Context variables

With every custom evaluation, there is a "return" variable that is used to set the response that is returned to the execution. Instead of adding your own "return" to the execution context, it is important instead, to simply set the value of the "return" variable so that your result can be returned. For example, if you wish to set the value of a Calculated Value you should do the following

DO THIS!

value = data.a + data.b;

DO NOT DO THIS!

return data.a + data.b;

The name of the variable that you set depends on what evaluation you are performing. Here is a list of all the "return" variable names for when they are used.

Evaluation	Return Variable	Type	Example
Custom Default Value	value	any	value = 'hello';
Calculated Value	value	any	value = data.a + data.b;
Custom Validation	valid	true when valid Error string when invalid	valid = (input === 'joe') ? true : 'Your name must be "Joe"';
Custom Conditionals	show	true when shown false hidden	show = !!data.showMe;
Logic Custom Trigger	result	true when logic should execute false otherwise	result = data.age > 18;

Custom Evaluation Context Variables

When a form is embedded in your application, it is also possible to inject custom Evaluation Context variables into the renderer. This is done via the options parameter of our renderer like so.

Formio.createForm(document.getElementById("formio"), "https://examples.form.io.example", {
  evalContext: {
    validatePhone: function(input) {
      return input.match(/^[2-9]\d{2}-\d{3}-\d{4}$/);
    }
  }
});

Now, when you create a form, you can use the following script within your custom Validation script.

valid = validatePhone(input) ? true : 'Phone number is invalid';

If you define custom Evaluation Context variables using the embedded code in your application, these methods will NOT be executed on the Server during server-side execution of your scripts. If you wish for them to also be evaluated, then you should use the "evalContext" configuration within the Form Modul

"instance" usage and methods

Anytime you create a new script, there is the ability to use "instance" to provide more advanced functionality to your custom evaluation. This variable refers to the current instance of the component variable that triggered the evaluation. While this variable does provide an enormous amount of flexibility, it should also be used with extreme caution since upgrades of our platform may alter some of the methods that are used within the instance method. For this reason, we prefer that ONLY the following methods and variables are used in conjunction with instance to ensure the greatest stability and upgrade path.

Property	Description	Example
instance.getValue()	Returns the value of the current instance component.	value = instance.getValue();
instance.setValue(...)	Sets the value of the component instance as well as forces the view to update as well.	instance.setValue("hello");
instance.updateValue(...)	Much like "setValue", but instead of also updating the "view", this simply updates the model and leaves the view as-is. This is helpful to call on an event when the <input> changes and you do not wish to create infinite loops.
instance.hasValue()	Returns true if the component has a value, false if it does not.	if (instance.hasValue()) { // Do something here... }
instance.dataValue	A "getter" to retieve the value of the component. This is similar to "getValue()" but does not have any side effects such as event emitting.	value = instance.dataValue;
instance.dataValue = '....'	A "setter" to set the value of a component. This is similar to "setValue()" but does not have any side effects such as event emitting.
instance.unset()	Unsets the value for this component in the data model.
instance.defaultValue	Returns the value of the default value for this component.
instance.getValueAt(num)	For a component with "multiple" checked, this allows you to get the value of a component at any index in the multiple array.
instance.setValueAt(index, val)	For a component with "multiple" checked, this allows you to set the value of a component at any index in the multiple array.
instance.options	The options passed to the renderer. Generally speaking, all options should remain reverse compatible and will not change from version to version.	if (instance.options.pdf) { // Only do something in pdf }
instance.component	Returns the JSON of the current component.
instance.root	Returns the "root" instance of the webform. Typically, this will point to either Webform or Wizard depending on which type of form you are using this within.
instance.refs	A map of all the DOM elements used within this component.
instance.errors	An array of all validation errors this component has, including the ones that are not visible in the UI.
instance.on(...)	Add a listener to this component to listen to specific events. CAUTION: using this method can cause serious memory leaks, it is preferred that if you use this, you should use it within the Custom Default Value evaluation since it is only ever executed once.
instance.emit(..)	Emit a custom event on this component.

Calculate Value On Server

Check this setting if you would like to run your calculations on the server side. This is useful if you wish to override the values submitted on the back-end with the calculations performed on the server.

Allow Manual Override of Calculated Value

Allows input data to override any calculations set on the field.

By default, the field value cannot be entered when a calculation is set on the field. Check this setting if you would like users to override the field calculation and set their own value.

Server Override

Overrides current component settings when the form submission is processed on the server side. Add this setting if you want the form component to behave differently on the server side.

It can be useful when conditional components in your form have the 'Omit Value From Submission Data When Conditionally Hidden' option disabled, but you want the hidden data to be removed after the form is submitted. In this case the 'Server Override' setting should be configured as follows:

{
    "clearOnHide": true
}

Validation

Settings found in the Validation Tab relate directly to the configurable Front-End and Back-End validations for the field. Validation covers settings such as required fields, unique data, min/max requirements, custom validations, and custom error messages.

Validate On

Determines when the field's front-end validation will occur based on the option selected:

Change - Validation will actively trigger any time there is a change in the field. This is the default option for every field.

Blur - Validation will only trigger when the field is no longer focused.

Use the Blur option on fields that require a certain format to ensure validation is not triggered until the user has completed the data input. EG Email field

Required

The Required setting is represented by a red asterisk next to the field label and forces the user to enter a value before the form is submitted or the user progresses to the next page of a Wizard form.

Unique

Upon submission, a query is done on the back end to ensure the data entered into the field is unique.

Apply this setting to an Email field on a registration form to ensure the address being entered has not been submitted to the database.

Validate When Hidden

When this setting is enabled, the component is validated when it is hidden or conditionally hidden. The validation errors of the hidden components are shown in the form errors alert when submitting the form.

A hidden component holding an invalid value while Validate When Hidden is enabled will prevent the form user from submitting the form, without giving them direct access to the component to correct the invalid value. Ensure the form workflow accounts for this behavior.

Minimum / Maximum Length

The Minimum or Maximum length requirement the field value must meet. This behavior changes depending on what component the setting is being applied to.

String (EG Text Field, Text Area) - Determined by the number of characters entered in the field

Number - (EG Number, Currency) - Determined by the numerical amount entered in the field

Array (EG Data Grid, Edit Grid) - Determined by the number of arrays or rows added to the grid

Use the Minimum / Maximum length on Data Grids or Edit Grids to determine the number of rows a user can add or remove. The minimum value will result in the grid rendering that specific number of rows when the form is displayed.

Regular Expression Pattern

Often referred to as Regex, this setting allows you to apply a pattern (or filter) that details a set of strings that must match the pattern. With a Regex Pattern set, the string must match the pattern before the form can be submitted.

Error Label

Change the field name displayed within the validation message when validation is triggered.

Use the Error Label when a field has a long label or name to shorten validation messages.

Custom Error Message

Write a Custom Error Message that overrides the default front-end validation message displayed on the form when validation is triggered.

Custom Validation

Expand the Custom Validation tab and write Javascript or JSON logic to set up your own validation rules for the field.

Click Here to read more about custom validation

Secret Validation

This setting hides the javascript validation rules defined within Custom Validation from the JSON form definition and component settings for any user that does not carry the Portal Base Project Administrative role.

While the validation will function normally for all users, non-administrative users will see the following JSON in the form definition: "customPrivate": true. Additionally, the Custom Validation JavaScript code block will be blank for these users when viewing the field settings.

Custom Errors

Set different custom error messages for multiple errors. For example, you could set up multiple error messages to communicate a required field and a min/max amount of characters (in contrast to “Custom Error Message”, which only allows you to set one error message for all errors).

API

Component settings found in the API Tab contain Back-End settings such as the field's Property Name as well as custom properties that can be set such as HTML and Tags.

Property Name

The back-end field identifier for the API endpoint. This field is auto-populated in camelCase based on the initial Label given to the field. Each field's Property Name must be unique on the form before the form can be saved.

Use the Property Name when referencing the field via API or conditional logic.

Field Tag

The Field Tag inherently does not provide any kind of functionality to the field, however, the tag can be used or referenced inside the application layer to facilitate different workflows or used to trigger within workflow logic in the form.

Custom Properties

Apply Custom Properties to the field.

Layout

Apply HTML Attributes / Properties and programmatically reposition PDF fields.

HTML Attributes

Provide a map of HTML attributes for the component's input element.

Attributes from other component settings or other attributes generated by form.io take precedence over the configured HTML Attributes.

PDF Overlay

These settings allow the user to programmatically control the field position on PDF First Forms as well as custom styles. Use the margins to fine-tune overlay component locations on your PDF Forms.

Style: Custom styles applied to the component when the PDF is rendered. Page: The PDF page the component will display on Left: The Left Margin of the component location within the PDF form defined in pixels. Top: The Top Margin of the component location within the PDF form defined in pixels. Width: The width of the component in pixels. Height: The height of the component in pixels.

Apply identical height measurements to all PDF overlay components to ensure a consistent height across all overlay components on the PDF form.

Conditions and Logic

Create intelligent workflows using Form.io's Conditions and Logic system. Show or hide your fields, merge component JSON schema, conditionally set field settings, and more, all based on user interaction on the form.

Click Here to learn more.