Form Renderer
A technical deep-dive into the powerful Form.io JavaScript Renderer

Introduction

One of the most significant differences between Form.io and other form products is how forms are rendered within applications. Most form platforms render forms on the Server (using technologies like PHP, .NET, Java, etc) and then send the rendered Form HTML up to the browser to be used. This approach has many problems, especially when being utilized within a modern mobile-first web application. In order to service the new Progressive Web Applications being developed today, Form.io has completely redefined how forms should be rendered so that they are flexible, extensible, and performant. Forms created within the Form.io builder are actually represented as JSON schemas that are then rendered directly within the application using a JavaScript rendering engine that we call the "Form Renderer". Here is an image that illustrates how this rendering works within a mobile application.
How the Form.io JavaScript Renderer works
The library responsible for this rendering can be found on Github @ https://github.com/formio/formio.js and is also Open Source so that any developer can fork and extend the functionalities provided by this library.

Getting Started

In order to fully understand how the Form.io Renderer works, it is important to try out the JavaScript renderer using real examples that you can easily walk through. To start, we will first create a new Project within the Form.io Portal @ https://portal.form.io, and then create a new simple form that we will use to test out the JavaScript renderer. Here is just an example of what your form may look like.
We will also want to make sure we copy the Form API url path (circled in the picture above) and save this for later when we wish to render the form. Now that we have our form, we can test out how this form will be rendered.
To test our the JavaScript Renderer, you can use one of many online web application editors. The ones that we recommend are:
For this demonstration, we will just go to JSFiddle and first add the following Resources.
  • https://cdn.form.io/formiojs/formio.form.min.js
  • https://cdn.form.io/formiojs/formio.form.min.css
  • https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css
These urls are described as follows:
  • formio.form.min.js - This is the minified JavaScript source code for the Form.io Renderer
  • formio.form.min.css- This is the minified CSS style sheets for the Form.io Renderer
  • bootstrap.min.css - This is the Bootstrap CSS Framework which Form.io uses to render forms.
Your JSFiddle should now look like the following.
This is the exact same thing as if you were building an HTML application from scratch and had the following HTML code.
1
<!doctype html>
2
<html lang="en">
3
<head>
4
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" crossorigin="anonymous">
5
<link rel="stylesheet" href="https://cdn.form.io/formiojs/formio.form.min.css" crossorigin="anonymous">
6
</head>
7
<body>
8
<script src="https://cdn.form.io/formiojs/formio.form.min.js" crossorigin="anonymous"></script>
9
</body>
10
</html>
Copied!
Next, we will add a place where we will render the form. We can do this by adding a single div tag into the HTML region and then giving it an "id" so that we can refer to it within our JavaScript initialization code (which we will write later). We can copy the following code into the HTML section of JSFiddle
1
<div id="formio"></div>
Copied!
It should look like the following.
This is the exact same thing as if we did the following in raw HTML
1
<!doctype html>
2
<html lang="en">
3
<head>
4
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" crossorigin="anonymous">
5
<link rel="stylesheet" href="https://cdn.form.io/formiojs/formiojs.form.min.css" crossorigin="anonymous">
6
</head>
7
<body>
8
<div id="formio"></div>
9
<script src="https://cdn.form.io/formiojs/formiojs.form.min.js" crossorigin="anonymous"></script>
10
</body>
11
</html>
Copied!

Rendering Form URL

And now for the fun part. We will now use the Form.io JavaScript SDK to instantiate the form that we just built within the Form.io Portal. We will do this by writing the following code within the JavaScript section of our JSFiddle.
1
Formio.createForm(document.getElementById('formio'), 'https://myproject.form.io/renderertest');
Copied!
Make sure you replace the project name "myproject" with the name of your project, and assuming that you named the test form the same as our example, you will see the following when you run the application in JSFiddle.
Here is the JSFiddle link for you to try this yourself.
The Form.io renderer is very flexible and as such can be configured to achieve many different use cases. Because of this, we have built a dedicated application that is used to demonstrate many of the features that our form renderer has to offer. This can be found at the following url.

Rendering Form JSON

In addition to rendering a URL, the form renderer can also be used to render simple JSON passed into the renderer like so.
1
Formio.createForm(document.getElementById('formio'), {
2
components: [
3
{
4
type: 'textfield',
5
key: 'firstName',
6
label: 'First Name'
7
},
8
{
9
type: 'textfield',
10
key: 'lastName',
11
label: 'Last Name'
12
},
13
{
14
type: 'email',
15
key: 'email',
16
label: 'Email'
17
},
18
{
19
type: 'button',
20
key: 'submit',
21
label: 'Submit'
22
}
23
]
24
});
Copied!
Which will render the form as follows.
If you wish to get the JSON of a form as you build it with the form builder, then we suggest that you check out the Form.io Builder Sandbox which can be found @ https://formio.github.io/formio.js/app/builder

Submission Data

Now that we have rendered a form, the next step will be to inject a submission into the form so that it will show data pre-populated within the form. One interesting thing to note about Form.io is that it completely separates the Form JSON from the Submission JSON and they are treated as separate JSON entities. Submission data will never be included as part of the form JSON. For example, the following Form JSON
1
{
2
"components": [
3
{
4
"type": "textfield",
5
"key": "firstName",
6
"label": "First Name"
7
},
8
{
9
"type": "textfield",
10
"key": "lastName",
11
"label": "Last Name"
12
}
13
]
14
}
Copied!
will take the following submission data JSON.
1
{
2
"data": {
3
"firstName": "Joe",
4
"lastName": "Smith"
5
}
6
}
Copied!
There are a couple of things to note here.
  1. 1.
    The submission data for the form is contained within a "data" object.
  2. 2.
    The "keys" for the submission data is determined by the "key" property of each component within the form.
You can alter the data structure by using dot-notation in the Form JSON which will allow you to alter the data construct of the submission. For example, if you wish to include the firstName and lastName fields within a "customer" data object, you could do the following.
1
{
2
"components": [
3
{
4
"type": "textfield",
5
"key": "customer.firstName",
6
"label": "Customer First Name"
7
},
8
{
9
"type": "textfield",
10
"key": "customer.lastName",
11
"label": "Customer Last Name"
12
}
13
]
14
}
Copied!
The dot-notation for the "keys" in this form tell the renderer to structure the submission as follows.
1
{
2
"data": {
3
"customer": {
4
"firstName": "Joe",
5
"lastName": "Smith"
6
}
7
}
8
}
Copied!

Data Components

Another way to alter the submission data construct is to use any of the Data Components within a form. These are special components that are used to not only visually show the data being collected in a data structured way, but will also change the data structure of the submissions being produced by the rendered form. For example, if you wish to produce the following submission data which is an array of children's first and last names, you can use the Data Grid component as follows.
1
{
2
"components": [
3
{
4
"type": "datagrid",
5
"label": "Children",
6
"key": "children",
7
"components": [
8
{
9
"type": "textfield",
10
"key": "firstName",
11
"label": "First Name"
12
},
13
{
14
"type": "textfield",
15
"key": "lastName",
16
"label": "Last Name"
17
}
18
]
19
}
20
]
21
}
Copied!
Produces the following submission JSON.
1
{
2
"data": {
3
"children": [
4
{
5
"firstName": "Joe",
6
"lastName": "Smith"
7
},
8
{
9
"firstName": "Mary",
10
"lastName": "Thompson"
11
]
12
}
13
}
Copied!
And for the Data Grid component, it looks like the following when being rendered.
There are other kinds of data components as described as follows.
Component
Type
Description
Data Grid
datagrid
Spreadsheet UI that stores an array of objects
Edit Grid
editgrid
Table UI that stores an array of objects, with inline edit
Data Map
datamap
Key-value pair where string key can be provided for dynamic values
Data Table
datatable
Grid UI that stores an array of objects
Container
container
Hidden container UI that stores components inside an isolated object.
Hidden
hidden
Hidden UI that can store any data value in any data structure.

Rendering Submissions

In order to render a submission, you must first render the form, and then set the form submission to the submission data you wish to render within the form. You can either render the form as JSON or as a form URL as described above, and then the submission is set once the form is done rendering. As a simple example, you can provide the following to demonstrate how a submission can be rendered within a form.
1
Formio.createForm(document.getElementById('formio'), {
2
components: [
3
{
4
type: 'textfield',
5
key: 'firstName',
6
label: 'First Name'
7
},
8
{
9
type: 'textfield',
10
key: 'lastName',
11
label: 'Last Name'
12
}
13
]
14
}).then((form) => {
15
form.submission = {
16
data: {
17
firstName: 'Joe',
18
lastName: 'Smith'
19
}
20
};
21
});
Copied!
Which will render as the following.
You can also render the submissions from a Form URL as the following demonstrates.
1
Formio.createForm(document.getElementById('formio'), 'https://examples.form.io/example')
2
.then((form) => {
3
form.submission = {
4
data: {
5
firstName: 'Mary',
6
lastName: 'Thompson',
8
}
9
};
10
});
Copied!
which will render as follows.

Rendering Submission API URL

The last way to render a submission is to render the submission via the API endpoint of that submission. This Submission API is described as follows.
get
https://yourproject.form.io
/:formName/submission/:submissionId
Retrieve a form submission
In order to utilize this rendering correctly, you will need to ensure that the user you are authenticated as has access to this submission. You can authenticate a user by setting a valid JWT token within the "formioToken" localStorage variable of your application.
This URL can then be added to the renderer to render a complete form with submission as follows.
1
Formio.createForm(
2
document.getElementById('formio'),
3
'https://examples.form.io/wizard/submission/5a542c9e2a40bf0001e0f8a9'
4
);
Copied!
Which will render the form and submission as follows.

Controlling the Form with JavaScript

One of the most powerful concepts of Form.io rendered forms is that you can control the rendered form using JavaScript. In most cases, this is done within the section of code that executes once the form has finished rendering. This is commonly referred to as the "Form Controller" section of the form renderer and can be seen as follows.
1
Formio.createForm(document.getElementById('formio'), 'https://examples.form.io/example')
2
.then((form) => {
3
// This section of code is the "Form Controller"
4
});
Copied!
The variable that is passed to this function can be called whatever you want, but form or instance are very common names. This variable is actually the Webform instance of the following source code.
Because of this, any method within these classes (and their derived classes) can be executed by referencing them on the form or instance variable. So many things can be accomplished using these variables. Here are just a few use cases that be done.

Log change events

1
// This section of code is the "Form Controller"
2
form.on('change', (changed) => {
3
console.log('Data was changed!', changed);
4
});
Copied!

Thank You Page after submission

1
// This section of code is the "Form Controller"
2
form.on('submitDone', function(submission) {
3
window.location = '/app/thanks.html';
4
});
Copied!

Custom Wizard Controls

1
// This section of code is the "Form Controller"
2
3
/**
4
* This code assumes a "wizard" is rendered, and that there are buttons in the
5
* wizard form that emit the events "gotoNextPage", "gotoPreviousPage" and
6
* "wizardSave"
7
**/
8
9
form.on('gotoNextPage', function() {
10
form.nextPage();
11
});
12
form.on('gotoPreviousPage', function() {
13
form.prevPage();
14
});
15
form.on('wizardSave', function() {
16
form.submit().then(function() {
17
form.onChange();
18
form.nextPage();
19
});
20
});
Copied!
This is such a powerful concept that there is actually a feature called the Form Controller where these controllers can be added to the form JSON and then will be executed in the same fashion as these indicate. This can be configured within the Form Settings of the form and you would use the variable name instance instead of form as shown above.

Form Renderer Options

In addition to rendering a form and providing submission data, you can also provide options to the renderer to control its behavior even further. The options are passed as the third parameter to the Formio.createForm method as shown below.
1
Formio.createForm(element, src|form, options)
Copied!
The options available are documented as follows.
Option
Description
Default
readOnly
Disables all input is set to true
false
noDefaults
Do not establish default submission values. Leave unset unless the user interacts with the form.
false
language
The current language for the renderer
en
i18n
The i18n configurations for the renderer. See Form Renderer Translations section
{}
viewAsHtml
Boolean to tell the renderer to render this form in "html" mode.
false
renderMode
The mode that the form should render within. This picks different render modes within the templates section. See Form Templates section for more information.
form
highlightErrors
Highlight the errors for each field.
true
componentErrorClass
The default CSS class to be applied to the error dom element.
formio-error-wrapper
template
The current template name
templates
Ability to add custom templates to the renderer. See Form Templates section.
iconset
The iconset to use within the renderer.
buttonSettings
For wizards only. Controls the settings and visibility of the wizard button settings. These are configured as follows.
{
"buttonSettings": { "showCancel": true, "showNext": true,
"showPrevious": true
"showSubmit": true }
}
{}
components
Allows for overrides for certain components rendered.
Example: Adds a prefix to all textfield components rendered.
{
"components": { "textfield": { "prefix": "hello" } }
}
{}
disabled
Allows for component overrides for disabled fields.
Example: Disable the firstName component.
{
"disabled": { "firstName": true }
}
{}
showHiddenFields
Boolean that, when set to true, will show all the hidden fields regardless of conditionals.
false
hide
Force certain components to be hidden regardless of conditionals.
Example: Hide the firstName and lastName components.
{
"hide": {"firstName": true, "lastName": true}
}
show
Force certain components to be shown regardless of conditionals.
Example: Show the firstName and lastName components.
{
"show": {"firstName": true, "lastName": true}
}
formio
Your own instance of the Formio class.
decimalSeparator
Used for Number components. Determines the decimalSeparator. Defaults to the browser default setting.
thousandsSeparator
Used for Number components. Determines the thousands separator. Defaults to the browser default setting.
fileService
A custom File Service instance.
hooks
Allows you to implement certain hooks within the renderer. See Form Hooks section.
These options can be applied to the renderer like the following example shows.
Example: Render a submission in read only mode.
1
Formio.createForm(document.getElementById('formio'), 'https://examples.form.io/wizard/submission/5a542c9e2a40bf0001e0f8a9', {
2
readOnly: true
3
});
Copied!

Form Properties

There are many different properties and methods that can be called on the form instance. Many of these methods are documented within the auto-generated SDK documentation found @ https://formio.github.io/formio.js/docs/
Within these documentations, you will see some of these methods described as follows.
While this documentation is helpful to understanding all the methods, here are few of the most used properties on the form instance.

form.form

The current form JSON that is loaded into the form.

form.submission

The current form submission JSON that is loaded into the form.

form.schema

A minified "schema" of the components loaded into the renderer. This is dynamically generated so use sparingly.

form.ready

A promise that is resolved when the form has finished rendered, submission data has been saturated, and the form is "ready".
1
form.ready.then(() => {
2
form.submission = {
3
data: {
4
firstName: 'Joe',
5
lastName: 'Smith'
6
}
7
};
8
});
Copied!

form.loading

Boolean to indicate if the form is currently loading (true) or not (false).

form.src

The current form source that is loaded within the renderer.

form.language

The current language for this form.

Form Methods

Here are few of the most used methods on the form instance.

form.setForm(form, [flags])

Sets the JSON schema for the form to be rendered. It returns a promise that resolves when the form has been completely rendered and attached.
Parameter
Description
form
The JSON schema of the form
flags
Optional flags to control the behavior of the change event loop.
1
form.setForm({
2
components: [
3
{
4
type: 'textfield',
5
key: 'firstName',
6
label: 'First Name',
7
placeholder: 'Enter your first name.',
8
input: true
9
},
10
{
11
type: 'textfield',
12
key: 'lastName',
13
label: 'Last Name',
14
placeholder: 'Enter your last name',
15
input: true
16
},
17
{
18
type: 'button',
19
action: 'submit',
20
label: 'Submit',
21
theme: 'primary'
22
}
23
]
24
});
Copied!

form.form = {...}

This is a "setter" alias for form.setForm. It can be used as follows.
1
form.form = {
2
components: [
3
{
4
type: 'textfield',
5
key: 'firstName',
6
label: 'First Name',
7
placeholder: 'Enter your first name.',
8
input: true
9
},
10
{
11
type: 'textfield',
12
key: 'lastName',
13
label: 'Last Name',
14
placeholder: 'Enter your last name',
15
input: true
16
},
17
{
18
type: 'button',
19
action: 'submit',
20
label: 'Submit',
21
theme: 'primary'
22
}
23
]
24
};
Copied!

form.setSubmission(submission, [flags])

Sets a submission and returns the promise when it is ready.
Parameter
Description
submission
The submission JSON you wish to set.
flags
Flags to control the behavior of the change event loop
1
form.setSubmission({
2
data: {
3
firstName: 'Joe',
4
lastName: 'Smith',
6
}
7
});
Copied!

form.submission = {...}

This is a "setter" alias for form.setSubmission. It can be used as follows.
1
form.submission = {
2
data: {
3
firstName: 'Joe',
4
lastName: 'Smith',
6
}
7
};
Copied!

form.setSrc(src, [options])

Set's the "src" of the rendered form. This is the API endpoint for either the Form URL, or the Submission URL. If you provide just a form src, then it will only load the form. If you provide a Submission URL, then it will load both the form and then saturate that form with the submission data.

form.src = '...'

A "setter" alias for form.setSrc.

form.language = '...'

Sets the language of the renderer.

form.loading = true

Sets the form to start loading (showing the spinner icon).

form.saveDraft()

Saves a draft submission.

form.restoreDraft(userId)

Restores a draft submission for a specific user ID

form.redraw()

Force a redraw of the form.

form.resetValue()

Force a reset value on the form.

form.submit()

Submit the form.

form.checkData()

Performs a check on the submission data for calculations, conditionals, and validations.

form.everyComponent(fn)

Iterate through every component within the form.
Parameter
Description
fn
A callback that will be called for every component. The signature for this component is as follows.
fn(component, components, index)
  • component - The component instance for the current component.
  • components - An array of the components that are the "siblings" of the component
  • index - The index of the component within the components being triggered.
1
form.everyComponent((component) => {
2
if (component.component.key === 'firstName') {
3
component.setValue('Joe');
4
}
5
});
Copied!

form.getComponent(path|key, [fn])

Retrieve a component from the form.
Parameter
Description
path|key
The key of the component you wish to fetch, or the data path of that component.
fn
Callback function to be called when the component is found.
1
const email = form.getComponent('email');
2
email.setValue('[email protected]');
Copied!

form.checkValidity([data], [dirty], [row], [silent])

Checks the form validity and updates the errors if the validity fails.
Parameter
Description
data
The data to check against. If no data is provided, then the submission data in context will be used.
dirty
If this should force the "dirty" flag on the components when performing the checks. If "true" this will highlight all invalid form fields as red on the form.
row
The row data to check against. If no data is provided, then the contextual row data will be used.
silent
If "true", then this will perform a passive check for validity and will not affect the visuals of the form and highlight any fields red if they are invalid.
1
if (!form.checkValidity(null, false, null, true)) {
2
alert('The form is invalid!);
3
}
Copied!

Form Events

Within the Form.io renderer, there are a number of events that are fired that allow you to respond to these events and then do something once they fire. A very common example of this is to listen for anytime someone changes a field within the form, log that change for audit reasons.
The Form.io renderer uses the EventEmitter3 library to manage all of the event handling that occurs within the renderer, and because of this, any method that this library includes can also be used within the renderer, as the following example illustrates.
1
// Listen for change events and log the changes as they occur.
2
form.on('change', (changed) => {
3
console.log(changed);
4
});
Copied!
The following events are triggered within the Form.io renderer.
Event
Description
Arguments
change
A value has been changed within the rendered form
  • changed: The changes that occurred, and the component that triggered the change. See "componentChange" event for description of this argument
  • flags: The change loop flags.
  • modified: Flag to determine if the change was made by a human interaction, or programatic
error
An event that fires when errors have occurred within the renderer
  • errors: An array of errors that occurred.
formLoad
The form json has finished loading
  • form: The form json that was loaded
submit
A form has been submitted
  • submission: The submission json object.
  • saved: Boolean to indicate if the submission was saved via API or not.
submitDone
Similar to "submit" but only fires when the submission is "saved" via API
  • submission: The submission json object.
submitError
Called when a submission error has occurred
  • error: The error that was fired.
render
The form is done rendering and has completed the attach phase.
  • element: The root element of the renderer
initialized
Called when the form has completed the render, attach, and one initialization change event loop
requestDone
Called when the Action url is provided to the renderer to submit to a custom action url. This is fired when the request is finished.
languageChanged
Called when the language has been changed.
saveDraftBegin
Called when a save draft has started
saveDraft
Called when a save draft operation has finished
  • submission: The submission that was saved as draft.
restoreDraft
Called when a draft submission has been restored into the renderer.
  • draft: The draft submission that was restored.
submissionDeleted
Called when a submission has been deleted.
  • submission: The submission that was deleted.
redraw
Triggered when a component redraws
focus
Triggered when an input component has received focus
  • instance: The component instance
blur
Triggered when an input component has been blurred
  • instance: The component instance.
componentChanged
Triggered when a specific component changes
An object containing the following properties.
  • instance: The component instance
  • component: The component json
  • value: The value that was changed
  • flags: The flags for the change event loop.
componentError
Triggered when an error occurs within a specific component
  • error: The error that has occurred.
submitButton
Triggered for button components configured as a Submit action, when they are clicked.
customEvent
Triggered for button components configured as Event action. This is fired when they are clicked.
An object containing the following properties.
  • type: The configured event type.
  • component: The component json
  • data: The contextual data for this button.
  • event: The click event
editGridAddRow
For EditGrid components, fired when a row has been added
An object containing the following properties.
  • component: The component json
  • row: The edit grid contextual row object.
editGridSaveRow
For EditGrid components, fired when a row has been saved.
An object containing the following properties.
  • component: The component json
  • row: The edit grid contextual row object.
editGridDeleteRow
For EditGrid components, fired when a row has been deleted.
An object containing the following properties.
  • index: The index of the row that was deleted.
fileUploadingStart
For File components, fired when a file upload has started
The file upload promise.
fileUploadingEnd
For File components, fired when the file upload had completed.
The file upload promise.
nextPage
For Wizards, this is triggered when the next page is navigated to.
An object that contains the following properties.
  • page: The current page
  • submission: The current submission.
prevPage
For Wizard, this is triggered when the previous page is navigated to.
An object that contains the following properties.
  • page: The current page
  • submission: The current submission
pagesChanged
For Wizard, this is triggered when the pages of the wizard changes.
wizardPageClicked
For Wizard, this is triggered when the wizard navigation page has been clicked.
  • page: The page that was clicked.
wizardPageSelected
For Wizard, this is triggered when the wizard page has been selected and is done rendering.
  • page: The page that was selected
  • index: The index of the page that was selected.

Hooks

Hooks allow you to alter the behavior of the form and block the execution of certain functionalities in favor of providing your own logic. A good example of this is to provide a beforeSubmit hook where you can block the submission and alter the the submission or even perform your own validations. Each hook is provided using the options of the renderer like so.
1
Formio.createForm(document.getElementById('formio'), 'https://examples.form.io/example', {
2
hooks: {
3
beforeSubmit: (submission, next) => {
4
// Alter the submission
5
submission.data.email = '[email protected]';
6
7
// Only call next when we are ready.
8
next();
9
}
10
}
11
})
Copied!
Here is a list of all available hooks within the renderer.

beforeSubmit(submission, next)

Allows you to hook into the submit handler before the submission is being made to the server. Each parameter is described as follows.
Param
Description
submission
The submission data object that is going to be submitted to the server. This allows you to alter the submission data object in real time.
next
Called when the beforeSubmit handler is done executing. If you call this method without any arguments, like next(), then this means that no errors should be added to the default form validation. If you wish to introduce your own custom errors, then you can call this method with either a single error object, or an array of errors like the example below.

Custom Errors

It is a very common use case to provide your own custom errors to the submit handler. To achieve this, you can call the next callback with either a single error object, or an array of errors you wish to introduce to the error handler. Here is an example of how to introduce some custom errors.
1
Formio.createForm(document.getElementById('formio'), 'https://examples.form.io/example', {
2
hooks: {
3
beforeSubmit: (submission, next) => {
4
// Make a custom ajax call.
5
$.ajax({
6
url: 'https://myserver.com/validate',
7
method: 'POST',
8
data: submission,
9
complete: (errors) => {
10
let submitErrors = null;
11
if (errors) {
12
submitErrors = [];
13
errors.forEach((error) => {
14
submitErrors.push({
15
message: error.toString()
16
});
17
});
18
}
19
next(submitErrors);
20
}
21
});
22
}
23
}
24
})
Copied!

Saving and Restoring submissions

This hook can also be used to ensure the integrity of submission data so that if any error occurs, the submission can be restored. The following code illustrates how this can be done.
1
Formio.createForm(document.getElementById('formio'), 'https://examples.form.io/example', {
2
hooks: {
3
beforeSubmit: (submission, next) => {
4
localStorage.setItem('currentData', JSON.stringify(submission.data);
5
next();
6
}
7
}
8
}).then(function(form) {
9
var currentData = localStorage.getItem('currentData');
10
if (currentData) {
11
form.submission = {data: JSON.parse(currentData)};
12
}
13
14
form.on('submitDone', function() {
15
localStorage.removeItem('currentData');
16
});
17
});
Copied!

beforeNext(currentPage, submission, next)

Allows you to hook into the submit handler before the switching to next page. Each parameter is described as follows.
Param
Description
currentPage
The current page data object. This allows you to use page data for your submissions on each page.
submission
The submission data object that is going to be submitted to the server. This allows you to alter the submission data object in real time.
next
Called when the beforeNext handler is done executing. If you call this method without any arguments, like next(), then this means that no errors should be added to the default form validation. If you wish to introduce your own custom errors, then you can call this method with either a single error object, or an array of errors like the example below.

Custom Errors

It is a very common use case to provide your own custom errors to the submit handler before user switching to next page. To achieve this, you can call the next callback with either a single error object, or an array of errors you wish to introduce to the error handler. Here is an example of how to introduce some custom errors.
1
Formio.createForm(document.getElementById('formio'), 'https://examples.form.io/example', {
2
hooks: {
3
beforeNext: (currentPage, submission, next) => {
4
// Make a custom ajax call.
5
$.ajax({
6
url: 'https://myserver.com/validate',
7
method: 'POST',
8
data: submission,
9
complete: (errors) => {
10
let submitErrors = null;
11
if (errors) {
12
submitErrors = errors.map(error => ({
13
message: error.toString()
14
}));
15
}
16
next(submitErrors);
17
}
18
});
19
}
20
}
21
})
Copied!

beforePrev(currentPage, submission, next)

Called before the previous page has been navigated.
Param
Description
currentPage
The current page data object. This allows you to use page data for your submissions on each page.
submission
The submission data object that is going to be submitted to the server. This allows you to alter the submission data object in real time.
next
Called when the beforePrev handler is done executing. If you call this method without any arguments, like next(), then this means that no errors should be added to the default form validation. If you wish to introduce your own custom errors, then you can call this method with either a single error object, or an array of errors like the example below.

customValidation(submission, next)

Provides a hook to inject custom validations into the submission process.
1
Formio.createForm(document.getElementById('formio'), 'https://examples.form.io/example', {
2
hooks: {
3
customValidation: (submission, next) => {
4
// Make a custom ajax call.
5
$.ajax({
6
url: 'https://myserver.com/validate',
7
method: 'POST',
8
data: submission,
9
complete: (errors) => {
10
let submitErrors = null;
11
if (errors) {
12
submitErrors = errors.map(error => ({
13
message: error.toString()
14
}));
15
}
16
next(submitErrors);
17
}
18
});
19
}
20
}
21
})
Copied!
Param
Description
submission
The submission data object that is going to be submitted to the server. This allows you to alter the submission data object in real time.
next
Called when the beforeSubmit handler is done executing. If you call this method without any arguments, like next(), then this means that no errors should be added to the default form validation. If you wish to introduce your own custom errors, then you can call this method with either a single error object, or an array of errors like the example below.

attachWebform(element, instance)

Called once the webform has started its attach phase.
Parameter
Description
element
The DOM element that the webform is attaching to.
instance
The webform instance object.
The method should either return the "element" or another DOM element that will be used to attach the webform object to.

beforeCancel()

Called before a form is canceled which provides the ability to abort the cancel process.
Example: If you wish to reject a form cancel process.
1
Formio.createForm(document.getElementById('formio'), 'https://examples.form.io/example', {