Intro to the Form.io Platform

Who needs a form? Anyone who needs data.

A form is ideal way to collect data because it is structured, responsive, scalable, and allows for live validation of data at input. This ensures the application is supplied with high-quality data that is fully and granularly accessible within the app.

Why is Form.io good for forms?

Form.io makes it easy to develop and deploy JSON-based forms. JSON-based forms are an ideal form solution because they ensure the form looks and behaves in a predictable way, and structures the data accordingly. This creates a user-friendly input and an application-friendly data output. Form.io’s APIs make it easy to access and use the data collected by a form elsewhere in the app.

Building a JSON-based form

Regardless of your development capability, Form.io makes it easy to develop a JSON-based form. Consider the following simple example, created by dragging and dropping a few components:

Drag-and-drop form building on the Form.io Developer Portal

The output of this is distilled into an easily readable JSON form:

Expand to view form JSON

{
    "display": "form",
    "settings": {
        "pdf": {
            "id": "1ec0f8ee-6685-5d98-a847-26f67b67d6f0",
            "src": "https://files.form.io/pdf/5692b91fd1028f01000407e3/file/1ec0f8ee-6685-5d98-a847-26f67b67d6f0"
        }
    },
    "components": [
        {
            "label": "Name",
            "applyMaskOn": "change",
            "tableView": true,
            "validateWhenHidden": false,
            "key": "name",
            "type": "textfield",
            "input": true
        },
        {
            "label": "Age",
            "applyMaskOn": "change",
            "mask": false,
            "tableView": false,
            "delimiter": false,
            "requireDecimal": false,
            "inputFormat": "plain",
            "truncateMultipleSpaces": false,
            "validateWhenHidden": false,
            "key": "age",
            "type": "number",
            "input": true
        },
        {
            "label": "Email Address",
            "applyMaskOn": "change",
            "tableView": true,
            "validateWhenHidden": false,
            "key": "emailAddress",
            "type": "textfield",
            "input": true
        },
        {
            "label": "Phone Number",
            "applyMaskOn": "change",
            "tableView": true,
            "validateWhenHidden": false,
            "key": "phoneNumber",
            "type": "textfield",
            "input": true
        },
        {
            "type": "button",
            "label": "Submit",
            "key": "submit",
            "disableOnInvalid": true,
            "input": true,
            "tableView": false
        }
    ]
}

In this basic example, it’s simple to see how a basic form makes it easy to collect and structure data. However, Form.io makes it easy to go far beyond such a basic example.

Each component in the Form.io platform is highly configurable. A suite of options for each component lets form builders control how a field is displayed, how input is validated, how the data is stored, and much more.

A small portion of the available component configuration options

With a little bit of customization, the simple form above becomes more useful. Tweaking a handful of settings increases the visual appeal of the form and improves the data quality.

Improved form style and structure

The changes configured to the form are readily observable in the Form JSON:

Expand to view modified form JSON

{
  "_id": "682c61f3e73395409926b96f",
  "title": "Race Registration",
  "name": "raceRegistration",
  "path": "raceregistration",
  "type": "form",
  "display": "form",
  "tags": [],
  "access": [
    {
      "type": "create_own",
      "roles": []
    },
    {
      "type": "create_all",
      "roles": []
    },
    {
      "type": "read_own",
      "roles": []
    },
    {
      "type": "read_all",
      "roles": [
        "682c523be733954099222afe",
        "682c523be733954099222b02",
        "682c523be733954099222b06"
      ]
    },
    {
      "type": "update_own",
      "roles": []
    },
    {
      "type": "update_all",
      "roles": []
    },
    {
      "type": "delete_own",
      "roles": []
    },
    {
      "type": "delete_all",
      "roles": []
    },
    {
      "type": "team_read",
      "roles": []
    },
    {
      "type": "team_write",
      "roles": []
    },
    {
      "type": "team_admin",
      "roles": []
    }
  ],
  "submissionAccess": [
    {
      "type": "create_own",
      "roles": []
    },
    {
      "type": "create_all",
      "roles": []
    },
    {
      "type": "read_own",
      "roles": []
    },
    {
      "type": "read_all",
      "roles": []
    },
    {
      "type": "update_own",
      "roles": []
    },
    {
      "type": "update_all",
      "roles": []
    },
    {
      "type": "delete_own",
      "roles": []
    },
    {
      "type": "delete_all",
      "roles": []
    },
    {
      "type": "team_read",
      "roles": []
    },
    {
      "type": "team_write",
      "roles": []
    },
    {
      "type": "team_admin",
      "roles": []
    }
  ],
  "owner": "66be1c053baf9e3e0b5f4c48",
  "components": [
    {
      "title": "Entrant Info",
      "collapsible": false,
      "key": "entrantInfo",
      "type": "panel",
      "label": "Panel",
      "input": false,
      "tableView": false,
      "components": [
        {
          "label": "Columns",
          "columns": [
            {
              "components": [
                {
                  "label": "First Name",
                  "applyMaskOn": "change",
                  "tableView": true,
                  "validate": {
                    "required": true
                  },
                  "validateWhenHidden": false,
                  "key": "firstName",
                  "type": "textfield",
                  "input": true
                }
              ],
              "width": 6,
              "offset": 0,
              "push": 0,
              "pull": 0,
              "size": "md",
              "currentWidth": 6
            },
            {
              "components": [
                {
                  "label": "Last Name",
                  "applyMaskOn": "change",
                  "tableView": true,
                  "validate": {
                    "required": true
                  },
                  "validateWhenHidden": false,
                  "key": "lastName",
                  "type": "textfield",
                  "input": true
                }
              ],
              "width": 6,
              "offset": 0,
              "push": 0,
              "pull": 0,
              "size": "md",
              "currentWidth": 6
            }
          ],
          "key": "columns",
          "type": "columns",
          "input": false,
          "tableView": false
        },
        {
          "label": "Age",
          "applyMaskOn": "change",
          "mask": false,
          "tableView": false,
          "delimiter": false,
          "requireDecimal": false,
          "inputFormat": "plain",
          "truncateMultipleSpaces": false,
          "validateWhenHidden": false,
          "key": "age",
          "attributes": {
            "size": "4"
          },
          "type": "number",
          "input": true
        },
        {
          "label": "Email Address",
          "applyMaskOn": "change",
          "tableView": true,
          "validate": {
            "required": true
          },
          "validateWhenHidden": false,
          "key": "emailAddress",
          "type": "email",
          "input": true
        },
        {
          "label": "Phone Number",
          "applyMaskOn": "change",
          "tableView": true,
          "validateWhenHidden": false,
          "key": "phoneNumber",
          "type": "phoneNumber",
          "input": true
        }
      ]
    },
    {
      "type": "button",
      "label": "Submit",
      "key": "submit",
      "disableOnInvalid": true,
      "input": true,
      "tableView": false
    }
  ],
  "pdfComponents": [],
  "settings": {

  },
  "properties": {

  },
  "project": "682c523be733954099222af0",
  "controller": "",
  "revisions": "",
  "submissionRevisions": "",
  "_vid": 0,
  "created": "2025-05-20T11:05:23.304Z",
  "modified": "2025-05-21T08:57:22.908Z",
  "machineName": "tyohvdhpejlkutb:raceRegistration",
  "plan": "trial"
}

How do I use my form?

A form is only as good as the ability to use it. Once a form as been built, it needs to be rendered and presented to the form users. This is handled by the Form.io Renderer.

The Form.io Renderer is a powerful JavaScript-based engine that transforms a JSON schema into a live form. The Form.io Renderer consumes the JSON schema, then constructs and displays the form directly within an application. This allows seamless integration with the framework used within the application (React, Angular, Vue), though it requires nothing more than plain JavaScript.

Where does the Form.io Renderer live?

The Form.io Renderer is embedded directly in the application. It consumes the JSON schema supplied to it and produces a form. The form JSON may exist directly within the application, but can also be linked remotely. This separates the business of application development and form development. Form builders are not constrained by limited developer resources, and application developers do not need to redeploy an application when the form is changed.

Example: The Formio 5k

Consider this example of an Angular app promoting a 5k race:

Formio 5k v1 - StackBlitzStackBlitz

Click to open a sample Angular App

Integrating a form into this app takes only a few steps:

1. Install the Form Renderer.

2. Install the AngularFormio library.

3. Import the Formio Module.

4. Embed the renderer.

Installing necessary dependencies

From the terminal, run the following commands to install Formio/JS and Angular/formio:

npm install formiojs@latest --save
npm install @formio/angular@latest --save

Import the Formio Module

In both main.ts and register.component.ts (as well as anywhere else Form.io is used), add the following statement:

import { FormioModule } from '@formio/angular';

Additionally, in each relevant component, add:

...
imports: [
    FormioModule
...

Embed the renderer

To embed a rendered form in the register.component.ts page, first add the following:

import registrationForm from './registrationForm.json';

There is currently a placeholder in register.component.ts, replace it with the following:

<formio [form]="form" (submit)="onSubmit($event)"></formio>

Finally, add the following to the end of register.component.ts:

export class RegisterComponent {
  form = registrationForm;

  onSubmit(submission: any) {
    console.log('Form submitted:', submission);
  }

A live embedded form can be seen here:

Formio 5k v1 - StackBlitzStackBlitz

The Angular app, with rendered form

This is one place where the power of the Form.io Platform becomes apparent. Since the form is designed completely separately from the app, and can be hosted anywhere the app can access, the ability to develop new forms or modify old ones is never bottlenecked by application development.

What happens when a form is used?

When the form user submits data through a form, the Form.io Renderer creates a submission, a JSON object recording the data entered in each component, along with some metadata about the user submitting the form, the environment, and more. This submission is stored in the Form.io Platform’s backend, powered by MongoDB. The structure of a submission mirrors the structure of the form.

How are submissions used?

Submissions, just like forms, are stored as JSON objects. A submission stores the data entered into each field of the form. Submissions may also include metadata about the form and the user submitting the form.

Submissions are stored in the Form.io Platform database. They can be viewed through the Developer Portal UI, programmatically accessed through a REST API, or downloaded as a PDF. Because the submission is a JSON object, it's easy to integrate that data into other aspects of the application, or parse it with a variety of third-party tools.

What is a Resource?

Resources in the Form.io platform are JSON objects that are defined just like a form. They can be designed with the same drag-and drop interface. Resources help structure data and enable the reuse of that data within forms and elsewhere within the application. They are accessible via REST API endpoint that is defined automatically when the resource is created.

A single form may supply data for multiple resources. Resources may also collect data from multiple forms. Additionally, resources can store data from non-submission sources through the use of the API.

Where are Forms and Resources managed?

Form builders create and manage forms and resources within the Form.io Developer Portal. The Developer Portal may be access through Portal.Form.io, or deployed to a hosted environment.

The Form.io Developer Portal hosts the drag-and-drop builder that lets users structure their form, define the behavior, and customize the presentation. It is also where developers may configure the Form.io Platform, enable integrations with other elements of the application stack, and manage Form.io Platform users.

Who uses the Form.io Developer Portal?

The Developer Portal is used by Form.io Platform developers, form builders, and application developers integrating the forms into the application.

Form users access the forms through the application that renders them, not directly from the Form.io Developer Portal.

Users of the Form.io Developer Portal are managed as resources within the deployment.

How is the Form.io Platform structured?

First, remember that the application contains the Form.io Renderer, and is where the end-user will interact with the form. On the backend, the Form.io Platform is containerized into

Broadly speaking, the fundamental elements of the cluster are structured like so:

• Enterprise Server:

  • Form building interface

  • REST API to store and access data

• MongoDB-compatible DB: (compatible with CosmosDB and DocumentDB)

  • Form and Resource schemas

  • Submission data

  • User resources

• PDF Server (Optional):

  • Serves PDF-first forms

• File Storage (Optional):

  • Blob storage for unstructured data

The Platform can be deployed to a variety of cloud services, on-prem servers, and even to a local machine.