LogoLogo
Getting StartedDevelopersDeployment GuideGet Help
  • Quick Links
  • Welcome to Form.io
    • Getting Started With Form.io
    • Launch a Form
    • Overview of Form.io
  • Developer Tool Ecosystem
    • PDF Solution
    • Enterprise Form Builder
    • Form View Pro
    • The Security Module
    • Accessibility Compliance Module
    • Developer License
    • SQL Connector - Deprecated
    • Integration Libraries
    • Form.io CLI Tool
  • User Guide
    • Introduction
    • Form.io Developer Portal
    • Teams
    • Projects
      • Project UI
      • Project Settings
      • Stages
      • Multi-Tenancy
    • Resources
      • ResourceJS
    • Forms
      • Form Creation
      • Form Types
      • PDF Forms
      • Embedding a Form
      • Form Revisions
      • Form Settings
    • Form Building
      • Form Builder UI
      • Form Components
        • Component Settings
        • Basic Components
          • Resource as Select Component Data Source
        • Advanced Components
        • Layout Components
        • Data Components
        • Premium Components
          • Nested Forms
        • Custom Components
      • Logic & Conditions
      • Existing Resource Fields
      • Actions
    • Submissions
      • Accessing Submissions
      • Importing Submissions
    • Form.io eSignature - Coming Soon
    • Form.io Reporting Module
    • PDF Template Designer
    • Form View Pro
    • Form Manager
    • Enterprise Form Builder Module
  • Developer Guide
    • Introduction
      • Application Development
      • API Documentation
    • Form Development
      • Form Renderer
      • Form Builder
      • Form Embedding
      • Form Evaluations
      • Form Templates
      • Custom Components
      • Translations
    • JavaScript Development
      • JavaScript SDK
      • JavaScript Frameworks
      • JavaScript Utilities
    • Authentication and Authorization
      • SAML
      • OAuth
      • LDAP
      • Resource Based Authentication
      • Email Authentication
      • Two-Factor Authentication
    • Roles and Permissions
      • Field Match-Based Access
      • Field-Based Resource Access
      • Group Permissions
    • Integrations
      • Email Integrations
      • File Storage
      • Google Developer Console
      • eSign Integrations
      • Relational Databases
    • Modules
    • Fetch Plugin API
    • CSS Frameworks
    • Offline Mode
    • Audit Logging
  • Deployments
    • Self-Hosted Deployment
      • Local Deployment
        • Local File Storage
      • Kubernetes
      • Cloud Deployment
        • AWS Deployment
          • AWS Lambda
          • Form.io/AWS Elastic Beanstalk End-To-End Encrypted Deployment
        • Azure Deployment
          • Azure App Service
            • Azure MSSQL Connector - Deprecated
          • Azure Virtual Machine
          • Azure Kubernetes Service
          • Set up the DB
        • GCP Deployment
          • GCP Cloud Run
      • On-Premise Deployment
      • Enterprise Server
      • PDF Server
    • Deployment Configurations
      • DNS Configuration
      • Load Balancer Configuration
    • Licenses
      • License Management
      • Library Licenses
    • Portal Base Project
      • Portal SSO
      • Portal Translations
    • Maintenance and Migration
      • Changes to Premium Libraries
  • FAQ
    • FAQ
    • Tutorials & Workflows
      • Password Reset
      • Dynamic Select Filtering
      • Approval Workflow
      • SSO Email Token
      • Embedding A Video
      • Data Source Validation
      • Select Data Source Options
      • Nested Form Workflows
        • Nested Wizard Forms
      • Save as Draft
      • Role-Based Conditions
      • Custom Component
      • Dynamic Radio and Select Box Values
      • Override CKEDITOR
    • Errors
    • Examples
    • License Utilization Checks
  • Contact Us
Powered by GitBook
On this page
  • Introduction
  • Embedding the Form Builder
  • Form Builder SDK
  • Formio.builder(element, [form], [options])
  • Form Builder Options
  • Events
  • Overriding Behavior

Was this helpful?

  1. Developer Guide
  2. Form Development

Form Builder

Learn how to use the Form.io JavaScript form builder

PreviousForm RendererNextForm Embedding

Last updated 1 month ago

Was this helpful?

Introduction

The Form.io Form Builder is an extension on the Form Renderer that allows for dynamic drag-and-drop building of the forms that will be rendered within the Form Renderer. The purpose of the form builder is to serve as a front-end user interface that is able to visually create the JSON schemas that are needed to be rendered into the form. For this reason, it can be thought of as a glorified JSON schema builder, where each field dragged onto the form creates the JSON schema of that component as it is configured. The following diagram illustrates this relationship between the form builder interface and the JSON schema that is being created.

Embedding the Form Builder

One great benefit of the Form.io form builder is it can also be embedded into your application just like the form renderer. It is very similar to the form renderer, which just a few minor changes. First we will need to open up a new JSFiddle and input the following configurations.

Add the following Resources.

The following CDN URLS hosts the Form.io JavaScript library and related resources. There are different CDN namespaces available for both the 4.x and 5.x renderers. Users who self-host the renderer can define custom URL formats and files to specify their preferred Form.io renderer version

Formio.js 4x

  • https://cdn.form.io/formiojs/formio.full.min.js

  • https://cdn.form.io/formiojs/formio.form.min.css

  • https://cdn.jsdelivr.net/npm/bootstrap@4.6.0/dist/css/bootstrap.min.css

  • https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.css

Formio.js 5x

  • https://cdn.form.io/js/formio.form.min.js

  • https://cdn.form.io/js/formio.form.min.css

  • https://cdn.jsdelivr.net/npm/bootstrap@4.6.0/dist/css/bootstrap.min.css

  • https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.css

Add the following HTML

<div id="builder"></div>

Add the following JavaScript.

Formio.builder(document.getElementById('builder'));

Once you do this, you will then see your Form Builder show up in the result panel.

This is a fully functional form building interface, which you can see by checking out the following JSFiddle.

Let's now explore all the options you can use to customize the form builder interface.

Form Builder SDK

In order to take advantage of the form builder, you need to understand all of the options available to you when working with the form builder interface. In all cases, the Form Builder is instantiated using the Formio.Builder method, which is defined as follows.

Formio.builder(element, [form], [options])

This method creates a new Form Builder interface within your application, and the following parameters can be applied.

Parameter

Description

element

The DOM element you would like to attach the form builder against.

form (optional)

Either the "src" or the form JSON you would like to use as the default form that shows up in the builder interface.

options (optional)

As an example, the following will create a new form builder, and then auto populate it with the form defined.

Formio.builder(document.getElementById('builder'), {
  components: [
    {
    	type: 'textfield',
      key: 'firstName',
      label: 'First Name'
    },
    {
    	type: 'textfield',
      key: 'lastName',
      label: 'Last Name'
    }
  ]
});

Which produces the following builder interface.

Optionally, you can provide the "src" to the form as follows.

Formio.builder(document.getElementById('builder'), 'https://examples.form.io/example');

Which produces the following builder interface.

The Formio.Builder method returns a promise that will resolve with the Form Builder instance, which can be used as follows.

Formio.builder(document.getElementById('builder'), {
  components: [
    {
    	type: 'textfield',
      key: 'firstName',
      label: 'First Name'
    },
    {
    	type: 'textfield',
      key: 'lastName',
      label: 'Last Name'
    }
  ]
}).then((builder) => {

  // Here is the form builder instance.
  console.log(builder);
});

In a later section we will go through some of the methods that can be used on the builder instance that will further enable customizations of the form builder interface.

Form Builder Options

The options of the form builder are passed as a JavaScript object to the Formio.Builder method like the following illustrates.

Formio.builder(document.getElementById('formio'), 'https://examples.form.io/example', {
    disabled: ['email']
});

The following are a list of options that can be passed to the Form Builder instantiation method.

Property

Description

disabled

An array of "keys" of components that should be disabled within the form builder. Example: ['firstName', 'lastName']

noNewEdit

Boolean (true) that makes it so that there is no modal that is shown when a component is dragged onto the form.

noDefaultSubmitButton

Boolean (true) that will not show a submit button by default in the builder.

alwaysConfirmComponentRemoval

Boolean (true) that will make every component removal show a confirmation message if you are sure you wish to remove the component (like layout components do).

formConfig

Form configurations to apply forms being created. These configurations are added to the "config" property of the form object.

resourceTag

The tag to use to query for the "Existing Resource Fields" section of the builder.

editForm

Options to apply to the Edit Form which is the form that shows inside the modal when you edit a component.

language

The language of the builder.

builder

display

The type of builder to be rendered. Must be 'form' (for a WebForm class), 'wizard' (for a Wizard), or 'pdf' (for a PDF form).

resourceFilter

Filter the resources that appear in the builder's Existing Resource Fields.

noSource

Don't link the resource ID in the builder's Existing Resource Fields.

alwaysConfirmComponentRemoval

If set to true, removing a component will always show an alert confirming that you want to delete the component.

language

The current language for the builder.

showFullJsonSchema

Show a component's entire JSON schema.

Builder Sidebar Configuration

These are the properties that can be set on the "builder" configuration option that is passed to the builder. This option is passed to the form builder like the following illustrates.

Formio.builder(document.getElementById('formio'), {}, {
    builder: {
        ...
    }
});

The properties in this configuration allow for the manipulation of the Builder sidebar as well as control the default schemas and behaviors of the fields that are added to Form Builder. By default, this property has the following configuration.

{
    resource: true, // Boolean to turn on or off "Existing Resource Fields" section
    basic: {
      title: 'Basic',
      weight: 0,
      default: true,
    },
    advanced: {
      title: 'Advanced',
      weight: 10
    },
    layout: {
      title: 'Layout',
      weight: 20
    },
    data: {
      title: 'Data',
      weight: 30
    },
    premium: {
      title: 'Premium',
      weight: 40
    }
}

Each of these sections can be turned off by simply adding a false for the value of that component.

For example, if we wish to turn off the Advanced, Premium, and Existing Resource Fields sections of the form builder sidebar, we could pass along the following configurations.

Formio.builder(document.getElementById('builder'), {}, {
    builder: {
        resource: false,
        advanced: false,
        premium: false
    }
});

This configuration can also be used to add Pre-defined components to the builder.

Adding Pre-Defined Components

A pre-defined component is a component that you provide the JSON configuration up front and then allow an end-user to drag-and-drop that component onto a form. A good example of this would be if you wish to have defined fields, such as "First Name" "Last Name" and "Email", instead of the field types, such as "Text Field", that are provided by default. Pre-defined fields can be added to the form builder using the builder as the following illustrates.

Formio.builder(document.getElementById('builder'), {}, {
    builder: {
        custom: {
            title: 'Pre-Defined Fields',
            weight: 10,
            components: {
                firstName: {
                    title: 'First Name',
                    key: 'firstName',
                    icon: 'terminal',
                    schema: {
                        label: 'First Name',
                        type: 'textfield',
                        key: 'firstName',
                        input: true
                    }
                },
                lastName: {
                    title: 'Last Name',
                    key: 'lastName',
                    icon: 'terminal',
                    schema: {
                      label: 'Last Name',
                      type: 'textfield',
                      key: 'lastName',
                      input: true
                    }
                },
                email: {
                    title: 'Email',
                    key: 'email',
                    icon: 'at',
                    schema: {
                        label: 'Email',
                        type: 'email',
                        key: 'email',
                        input: true
                    }
                },
                phoneNumber: {
                    title: 'Mobile Phone',
                    key: 'mobilePhone',
                    icon: 'phone-square',
                    schema: {
                        label: 'Mobile Phone',
                        type: 'phoneNumber',
                        key: 'mobilePhone',
                        input: true
                    }
                }
            }
        }
    }
});

The default schema for each of these fields is defined in the schema property of that component, which means that as the user drags-and-drops the field on to the form builder, this is the schema that will be used to default that field on the form. The following configuration produces the following form builder.

Events

The following form builder events are emitted from the form builder as the user is building forms.

Event

Description

Arguments

addComponent

Triggered every time a component is added to the form via the builder drop operation.

  • info: The component information that was added to the form.

  • parent: The parent component information.

  • path: The component path for this dropped component

  • index: The index within the parent for this component.

  • isNew: Boolean to indicate if the component is "new" to the form. "false" means it was dragged and dropped from elsewhere on the form.

removeComponent

Triggered when a component is removed by the form builder.

  • component: The component being removed.

  • schema: The component minified json schema

  • path: The component path for this dropped component

  • index: the index within the parent for this component.

updateComponent

Triggered when a component has been updated within the form builder

  • component: The component being updated.

builderFormValidityChange

Triggered when the builder highlights some fields as invalid

  • hasInvalidComps: Boolean if there are invalid components.

Overriding Behavior

With the form builder, however, you can override the Component forms for each component by modifying the editForm property of that component. This property is a function that accepts other overrides and then returns the Form.io Form of that component edit form. As an example, the following will change the Text Fields edit form to ONLY contain the label.

Formio.Components.components.textfield.editForm = function() {
  return {
    components: [
      {
        type: 'textfield',
        key: 'label',
        label: 'Label'
      }
    ]
  };
};

It should be noted that the key of each of these components need to correlate to the property name of the Component JSON. So for example, if you wish to include a field for the Required property, you can use the following schema.

Formio.Components.components.textfield.editForm = function() {
  return {
    components: [
      {
        type: 'textfield',
        key: 'label',
        label: 'Label'
      },
      {
        type: 'checkbox',
        key: 'validate.required',
        label: 'Required'
      }
    ]
  };
}; 

With the same methods as described in the Overriding Form Renderer documentation, you can also modify the existing edit form using a method similar to the following.

var textFieldEditForm = Formio.Components.components.textfield.editForm;
Formio.Components.components.textfield.editForm = function() {
  var editForm = textFieldEditForm();
  
  // Make changes to the editForm here!
  
  return editForm;
};

For a great interactive visual on how the Form.io Form Builder works, we highly recommend visiting the Form Builder Demo @ to visually see how building a form and configuring the components can modify the JSON of the form in real time.

Navigate to the following link for more information on

See section.

See

Just like the Form Renderer, the form builder can also be overridden in a very similar way to what is described in the section of the Form Renderer documentation.

https://formio.github.io/formio.js/app/builder
Form Builder Options
Builder Sidebar Configuration
Form.io CDNs
Form.io Form Builder creating a JSON schema
Illustrates how the form builder can be embedded in an application
Overriding Behavior