Premium Components

Instructions for Use of Form.io Premium Components 
Form.io provides access to private modules that contain premium components and themes for enterprise plans. In order to use them, you will need to be granted access and use the pkg.form.io registry to install the modules.
1.Ensure you have a form.io user account. Contact [email protected] and request access to private modules.
2.Go to https://pkg.form.io and log in with the username and password of your form.io account. Please note that this is the USERNAME and not email address of your account in form.io. You can access your username by logging into portal and going to your account information at the top right. If you are able to log in to https://pkg.form.io then you have been granted access and are using the correct username and password.
3.From within your project, log in to the package registry by running the following command:
1
npm adduser --registry https://pkg.form.io
Copied!
Enter the same username and password from step 2.
4.Find the package you want to install in your app. Premium is a very common one. To install it, from the command line in your app.
1
npm install @formio/premium --registry https://pkg.form.io
Copied!
This will install the package within your application.
5.To use it, in the main file of your app, Formio.use() the package. Depending on your language, do something like the following. (With react or vue, import Formio from react-formio or vue-formio instead of formiojs).
1
import { Formio } from 'formiojs';
2
import premium from '@formio/premium';
3
​
4
Formio.use(premium);
Copied!
6.Render forms as usual. Premium components will now be installed in your app.
The Premium Components
Dynamic Wizard
A Dynamic Wizard is similar to the Edit Grid in that it also allows you to collect an array of object values and then constructs as table view as you add new rows, but filling an array element occurs in steps, where each component inside the Dynamic Wizard is a separate step.
The principle of operation is based on the behavior of the Wizard, but when you go to the next steps, the current page of the Wizard remains the same. The table view of the filled data appears with the successful passage of the last step, or when you click on the cancel button.
By default, the component is empty but can have other form components placed inside.
Dynamic Wizard is only available for the Wizard forms and does not work inside the Webforms.
Dynamic Wizard display in the sidebar and the edit form
The example below illustrates four form components placed inside the Dynamic Wizard. Layout components can be used to group the form components.
Only one Dynamic Wizard can be placed into a Wizard page. In order to add another one, add a new Wizard page and place the Dynamic Wizard in there.
Dynamic Wizard cannot be placed inside another Dynamic Wizard.
Below is an example of the Dynamic Wizard in the 'Edit mode' displayed in the rendered form.
In the 'Edit mode' each component follows the other ones in an order they have been placed into the Dynamic Wizard. Using the example above with the Dynamic Wizard with four components, the 1st component will be the Text Field, followed by the Password field, followed by the Field Set with the Text Area and the Number component (form components, grouped by Layout components, display together in one step in the 'Edit mode'). 
Once the component is filled in, press the 'Next' button to proceed to the next step.
If you want to go back to the previous step(s) to seethe already entered values or make some changes, press the 'Previous' button.
When in the 'Edit mode', only the Dynamic Wizard displays in the Wizard page. All the components outside the Dynamic Wizard will show up after the user leaves the Dynamic Wizard 'Edit mode'.
The Dynamic Wizard always initialzied in the 'Edit mode' (e.g. on form load when the Dynamic Wizard is in the 1st Wizard page or after switching to another Wizard page that contains the Dynamic Wizard).
Dynamic Wizard in the 'Edit mode' in the rendered form - Step #1
Dynamic Wizard in the 'Edit mode' in the rendered form - Step #2
Dynamic Wizard in the 'Edit mode' in the rendered form - Step #3
With the successful passage of the last step, the table view of the filled data appears.
If you want to edit the saved data entry, press the 'Edit Row' button next to the appropriate entry. The Dynamic Wizard will then enters the 'Edit mode' again where you'll be able to make changes to the saved data.
If you want to remove a certain data entry, just press the 'Remove Row' button.
Dynamic Wizard with 1 data entry in the rendered form
If you want to add a new data entry, press the 'Yes' button below the saved data entries as displayed in the screenshot below. The Dynamic Wizard will then enter the 'Edit mode', which will allow you to create a new data entry.
Dynamic Wizard with 1 data entry in the rendered form
Below is a list of the main settings of the Dynamic Wizard component.
Dynamic Wizard main component settings
Below is an in depth look at the specific Dynamic Wizard options that users can add or interface with.
Dynamic Wizard specific component settings
Header, Row and Footer Templates: Dynamic Wizard gives the user flexibility to customize the grid to how they see fit using basic JavaScript. Within the Template section of the component settings, the user can modify what type of components are displayed within the grid row along with the header / footer.
​
Data Source
‌Data Source component is a form component which can be used for fetching data from some external source using an API endpoint. It is hidden and can be used only for storing some data loaded from an external data source.
‌Example use cases:
Perform custom validation based on some external data
Display some info from the external source to user (e.g. weather, currency exchange rate etc.) (See examples to learn how to display value from the Data Source component)
Save some external data in the submission fir the future use or calculations (e.g. currency exchange rate on the moment of submission)
Below is a list of the Trigger settings of the Data Source component.
Data Source component Trigger settings
Trigger on Form Init: ‌Loads data once the form is rendered and ready for use.
‌Trigger on Server: Loads data on the server during validation.
‌Trigger on Data Change: Specifies a component the value change of which will have the data stored in the Data Source component be refreshed. A new request will be sent again.
‌Trigger on Blur of Component: ‌Specifies a component on which blur, data stored in the Data Source component should be refreshed. A new request will be sent again.
‌Trigger on Event: ‌Specifies a name of the event on which data stored in the Data Source component should be refreshed. A new request will be sent again.
‌Triggered Event: ‌If specified, an event with the specified name will be triggered once the data load was triggered.
Below is a list of the Fetch settings of the Data Source component.
Data Source component Fetch settings #1
‌
Data Source Type: ‌Specifies a source type from which data will be fetched. Available options: URL, IndexedDB.
‌Data Source URL: The API endpoint to which a request is made to retrieve data.
‌Method: ‌The method to be used when making a request to the specified endpoint. Available options: GET, POST.
‌Request Headers: ‌An HTTP request headers to be used when making a request to the specified endpoint.
‌Forward Headers: Forwards the headers passed to the server to the fetch endpoint.
​Form.io Authentication: ‌Passes Form.io Authentication headers with the request.
​Enable To Store Request Result in the Cache: ‌If checked, the result of each API call to the specified endpoint will be cached. That means, if the Data Source refresh is triggered again with the same URL, it won't make a real request to that URL, but rather take the result of the previous request with the same URL from the cache.
Uncheck the setting, if the data which the URL returns updates frequently and you want to keep it up-to-date.
Data Source component Fetch settings #2
Choose From Existing Databases?: Allows selecting an existing database.
Database Name: The name of the indexedDB database.
Table Name: The name of a table in the indexedDB database.
Data Source component Fetch settings #3
Existing Database Name: The name of the existing indexedDB database.
Existing Table Name: The name of an existing table in the indexedDB database.
‌Example Forms:
1.Show State by the entered abbreviation using Data Source
Form Embed URL: https://gtbvdrunldplvre.form.io/datasourceexample1​
2.Show States Abbreviations Cheat Sheet using Data Source
Form Embed URL: https://gtbvdrunldplvre.form.io/datasourceexample2​
​
reCAPTCHA
The Form.io reCAPTCHA component implements reCAPTCHA v3.
Below is a list of the main settings of the reCAPTCHA component.
reCAPTCHA component settings
Type of Event: Event which the reCAPTCHA component would react to.
Button Key: API Key of the button for the reCAPTCHA component to react to (only for 'Button Click' type of event).
Project Settings
If you want to use reCAPTCHA component on your forms, you need to set reCAPTCHA’s Site Key and Secret Key in your Project Settings on portal:
1.Go to your project on portal > Settings > Integration > Google reCAPTCHA 
2.Specify a Site Key and a Secret Key from your Google reCAPTCHA Admin Panel​
3.Save the Settings
Google reCAPTCHA integration settings
As a result, your project will have following in its JSON:
1
 "settings": {
2
   "recaptcha": {
3
     "secretKey": "your_secret_key",
4
     "siteKey": "your_site_key"
5
   }
6
 }
Copied!
Render From URL
The easiest way to use reCAPTCHA component is to add it to your form using our form builder and render using its URL. In this case you don’t need to do any additional work, just do following:
1
Formio.createForm(document.getElementById('formio'), 'your_form_url').then(function(form) {
2
  // Provide a default submission.
3
  form.submission = {
4
    data: {
5
    }
6
  };
7
});
Copied!
Render From JSON
If you want to render form from JSON, you’d also need to do following:
1.Your form should have following settings added to its JSON:
1
 {
2
     "settings": {
3
         "recaptcha": {
4
             "isEnabled": "true",
5
             "siteKey": "your_site_key"
6
         }
7
     }
8
 }
Copied!
2.Before rendering form you need to set Project URL to the URL of project where you have your reCAPTCHA Secret Key set in settings:
1
 Formio.setProjectUrl('<your_project_URL'); //for ex. https://examples.form.io/
Copied!
After above is done you can render the form from JSON:
1
Formio.createForm(document.getElementById('formio'), 'your_form_json').then(function(form) {
2
  // Provide a default submission.
3
  form.submission = {
4
    data: {
5
    }
6
  };
7
});
Copied!
How It Works
When you add the reCAPTCHA component to the form, you can specify if it’s going to trigger on Form Load or Button Click (for Button Click you’ll also need to specify to which button it should react).
Trigger on Form Load
When your form with Form Load reCAPTCHA emits ‘formLoad’ event, we send verification request to Google for action called ‘<your_form_name>Load’. Google’s responce becomes the submission value of your Form Load reCAPTCHA component:
1
{
2
  "data": {
3
    "reCaptcha": { 
4
      "success": true,
5
      "challenge_ts": "2019-01-11T10:29:39Z",
6
      "hostname": "your_domain",
7
      "score": 0.9,
8
      "action": "<your_form_name>Load" 
9
    }
10
  }
11
}
Copied!
Trigger on Button Click
When any button is clicked on your form, our renderer searches for Button Click reCAPTCHA component tied to a button with same API Key as clicked one. If renderer finds this reCAPTCHA component, we send verification request to Google for action called '<your_button_key>Click'. Google's responce becomes the submission value of your Button Click reCAPTCHA component:
1
{
2
  "data": {
3
    "reCaptcha": { 
4
      "success": true,
5
      "challenge_ts": "2019-01-11T10:29:39Z",
6
      "hostname": "your_domain",
7
      "score": 0.9,
8
      "action": "<your_button_key>Click" 
9
    }
10
  }
11
}
Copied!
Example
Please see this example of rendering form with reCAPTCHA component.
​
Resource
A Resource component allows users to reference other resources in your project. For example, if you have a Director resource and a Movie resource, you can add the Resource field on the Movie to reference the Director.
The Resource component is deprecated. Use the Select component with data source of "Resource" instead.
Below is a list of the main settings of the Resource component.
Resource component settings #1
Resource: The resource to be used with this field.
Select Fields: The properties on the resource to return as part of the options. If left blank, all properties will be returned.
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.
Resource component settings #2
Filter Query: Provides additional filtering using query parameters.
Sort Query: Provides additional sorting using query parameters.
Item Template: The HTML template for the result data items.
Add Resource: Allows to create a new resource while entering a submission.
Add Resource Label: Allows to set the text of the Add Resource button.
Resource component settings #3
​
File 
A File component allows users to upload and download files to a form. In order to use the File component, 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.
Below is a list of the main settings of the File component.
File component main settings
Below is a list of the specific settings of the File component.
File component specific settings #1
Storage: This is the storage provider where the file will be stored and accessed from. Select the appropriate provider. All providers besides URL and IndexedDB require additional configuration in project settings.
Directory: This field will append all files with the string so that they are in a directory on the storage provider. Must end in “/”.
File Name Template: Allows specifying a template for a name of uploaded file(s). Regular template variables are available (data, component, user, value, moment etc.), also fileName, guid variables are available. Theguid part must be present. if not found in template, will be added at the end.
Upload Only: Allows only to upload file(s) and consequently the download, in this component, will be unavailable.
Display As Image(s): Instead of a list of linked files, images will be rendered in the view. 
Image Size: The image size in pixels for previewing images.
File component specific settings #2
Enable Web Camera: Allows using an attached camera to directly take a picture instead of uploading an existing file.
Webcam Width: The webcam size in pixels for taking pictures.
File Types: Allows specifying file types to classify the uploads. This is useful if you allow multiple types of uploads but want to allow the user to specify which type of file each is.
File Pattern: Allows specifying file extentions that will be allowed to upload. All the other file extensions that are not specified in this field won't be upload.
File Minimum Size: Allows setting a minimum file size for uploaded files.
File Maximum Size: Allows setting a maximum file size for uploaded files.
For more information on how to specify file patterns and sizes, visit https://github.com/danialfarid/ng-file-upload#full-reference.
File component specific settings #3
URL:  The URL of the service to post the files to. It must be compatible with the ng-file-upload service and return an object that includes the URL to access the file.
For more information on how to set up the server, visit https://github.com/danialfarid/ng-file-upload#server-side.
Custom Request Options: Allows passing the custom xhr options.
File Form-Data Key: Key name that you would like to modify for the file while calling API request.
Private Download: Makes the file download send a POST request to the download URL with the x-jwt-token header. This will allow your endpoint to create a Private download system.
File component specific settings #4
Database: The name of the indexedDB database.
Table: The name of a table in the indexedDB database.
​
Nested Form
Nested Form component allows you to insert one (child) Resource/Form with all its fields into another (parent) Resource/Form.
For example, if you have Song resource (parent) and Artist resource (child) and you want to create both Song and Artist submissions by submitting one form, you may use Nested Form component for this case.
Name
The label for this field that will appear next to it.
Hide Label
Check if you want to hide the label when your parent form is rendered
Label Position
Choose where to render the label relatively to the Nested Form component itself
Form
Select a child Form/Resource that you’d like to nest into parent form
Custom CSS Class
CSS class / classes (space separated) that will be added to component’s element
Save as reference
Check if you’d like to save only _id of child form submission instead of storing all child submission object inside of parent submission. This will also help all changes you’ve made in child submission be reflected in parent submission. If not checked, whole child submission object will be saved, and no any child submission changes would be reflected in parent submission.
Nested Forms for remotely deployed project
If your project is remotely deployed with subdirectories, then you need in your app call
1
 Formio.setProjectUrl(<project_URL>). 
Copied!
This will help Formio understand where to fetch nested resources from and will set up base URLs properly.
Component Data
The Component ‘Data’ settings will allow you to configure the way your data is saved, rendered, or calculated on your field.
Default Value
Default value will be the value for this field, before user interaction. Having a default value will override the placeholder text.
Input Format
Input Format setting protects from cross-site scripting attacks. Input types default to ‘Plain’, but ‘HTML’ as well as ‘Raw’ can be selected.
Database Index
Set this field as an index within the database which can increase performance for submission queries. Note - this setting is only available on the Enterprise plan and must have a Submission Collection set in order to activate.
Custom Default Value
Write JavaScript or JSON to customize the value the field will be defaulted to.
Calculated Values
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.
Also you have access to special util variable - library of useful functions. More information about util library could be find 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.
Calculate on Server
Perform the custom calculations on the server as well as the frontend.
​
Sketchpad
Work in progress
Tagpad
Work in progress
Data Table
Data Table Component allows you to easily work with large sets of data. It is similar to the Edit Grid. Data Table also allows you to collect an array of object values and then constructs as table view as you add new rows, but it also supports showing/hiding of columns, pagination, sorting, and filtering to find needed data and etc.
Example of Data Table Component
Showing/Hiding of columns
Allows you to show only columns you need now.
Pagination
Allows you to show manipulate a big bunch of data by separating it into smaller pieces - pages. You can go to the first/previous/next/last page and choose the size of a page.
Sorting
Allows you to sort data in Data Table using arrow buttons in the header or "Sort Ascending" and "Sort Descending" buttons in column menu.
Filtering
Allows you to filter data in Data Table using the "Filter" section in column menu.
Provided filter operations such as "contains", "matches", "less than", "greater than", "equals", "not equals" and etc.
Inline Editing
Allows you to edit data of Data Table with no need to open Edit Modal. Just like in Excel.
Set up Data Table with Data Source
1.Add Data Table and Data Source. Add Components to Data Table with Property names corresponding to the field names in the data from api. Make sure that Table view is checked for every component you want to see in table.
2. Set your Data Source URL on Fetch tab and Trigger on form init on Trigger tab
3. Go to Data tab of Data Table Component and set Redraw on to Data Source and Calculated Value to value = data.dataSource
4. That's it! Go to Use tab and check out.
Configuration
Field
Description
Sortable
If checked, allows you to sort data in Data Table.
Filterable
If checked, allows you to sort data in Data Table.
Inline editing
If checked, allows you yo edit data with no need to open Edit Modal.
Items per page
Allows you to choose default page size of data displayed in Data Table.
Show add button
If checked, allows you to add data to Data Table.
Show edit button
If checked, allows you to edit data in Data Table.
Show delete button
If checked, allows you to delete data from Data Table.
Show delete all button
If checked, allows you to delete data from Data Table.
Delete all confirmation message
Allows you to configure confirmation message before delete all. Visible only when Show delete all button is checked.
Child Components
Every non-Layout child Component has "Column weight in DataTable" and "Hide column in Data Table by default" fields. They indicate should columns in Data Table appear in a different order in the table or not, and should they be hidden by default.
You can add Button Components, HTML Element Components and Content Components into Data Table and configure them to add dynamic bechaviour using row variable.
Add Button Component inside Data Table, set its Action to Custom. Then add alert(JSON.stringify(row, null, 2)); line to Button Custom Logic field to see JSON data of row.
You also can use row and rowIndex variables in HTML Element Component and Content Component to customize their view for each row.
For example, set this code to Content field of HTML Element Component and you will see a simple inline chart based on the number field.
1
<div style="width: {{row.number}}%; height: 30px; background: {{row.number > 60 ? '#3fb618' : row.number > 20 ? '#ffdc31' : '#e25652'}}">
2
  <b>&nbsp;{{row.number}}%</b>
3
</div>
Copied!
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.
1
{
2
  "type": "custom",
3
  "isNew": true,
4
  "key": "custom",
5
  "protected": false,
6
  "persistent": true
7
}
Copied!
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.
1
app.config([
2
  'formioComponentsProvider',
3
  function (formioComponentsProvider) {
4
    formioComponentsProvider.register('checkmatrix', {
5
      title: 'Check Matrix',
6
      template: 'formio/components/check-matrix.html',
7
      settings: {}
8
    });
9
	}
10
]);
Copied!
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.
​