Form Templates

Describes the Form.io Form Templating System

The Form.io templating system allows developers to modify the look-and-feel of their organization's forms by exposing APIs that can inject custom CSS classes into specific elements in a component or can change the underlying HTML structure of a component entirely. You can either create an entire template for all components, or simply override existing templates if you wish to just alter a few of the components.

Form.io currently maintains two open source framework templates:

• Bootstrap - https://github.com/formio/bootstrap
• United States Web Design System (USWDS) - https://github.com/formio/uswds

There are some additional templates that have been developed by our open source community:

• UK Government Design System - https://github.com/DigitalPatterns/formio-gds-template
• Bulma - https://github.com/formio/bulma

What is a template?

In this document, a "component template" refers to the combination of an underlying DOM structure paired with CSS classes, inline styles, and other contextual state. The @formio/js rendering engine receives these component templates in the form of pre-compiled functions that return HTML strings; these functions are then called when the components are rendered to the DOM.

A "template" in this document refers to a collection of component templates. Examples of templates are the Form.io Bootstrap template and the Form.io USWDS template.

Framework Templates

By default, the @formio/js renderer uses the Form.io Bootstrap 5-based template. To use another template, import the template object and pass it as an argument to Formio.use.

import { Formio } from '@formio/js';
import { bootstrap4 } from '@formio/bootstrap';

// use the Bootstrap 4-based template instead of the default
Formio.use(bootstrap4);

import { Formio } from '@formio/js';
import uswds from '@formio/uswds';

// use the USWDS-based template instead of the default
Formio.use(uswds);

Overriding Templates at Runtime

In addition to setting the global CSS Framework, you can override specific component templates within that framework by modifying the global Templates object at runtime. Each component template consists of a group of pre-compiled functions that return HTML strings. Each of these pre-compiled functions corresponds to a render mode, but for the purposes of this document we will focus on the most common, the "form" render mode.

import { Templates } from '@formio/js';

// override the "input" component template (used by components that contain a text input)
const myInput = (ctx) => `<div class="${ctx.component.type}">${ctx.value}</div>`;
Templates.current.input.form = myInput;

import { Templates } from '@formio/js';

// override the "input" and "html" component templates
Templates.current = {
  input: {
    form: (ctx) => '<div>My custom template</div>'
  },
  html: {
    form: (ctx) => '<div>My other custom template</div>'
  }
};

Overriding Specific Templates

Component templates are often consumed by multiple components. For example, the input template is consumed by components that contain a text input element; any overrides to the input template therefore could affect many of components in a form. To enable overriding a specific component template in a form, Form.io namespaces each component with its type and its key. For example, given a form with a firstName Text Field component and a lastName TextField component, you can:

• override each input component template

  Templates.current = {
    input: {
      form: (ctx) => '<div>Template Overridden!</div>'
    }
  };

• override only the Text Field component template using the template name ("input") and the template type ("textfield")

  Templates.current = {
    'input-textfield': {
      form: (ctx) => '<div>Template Overridden!</div>'
    }
  };

• override only the firstName component template using the template name ("input"), the template type ("textField"), and the component key ("firstName" )

  Templates.current = {
    'input-textfield-firstName': {
      form: (ctx) => '<div>Template Overridden!</div>'
    }
  };

Documentation - Specific Template Overrides - JSFiddle - React, Tailwind, and code Playgroundjsfiddle.net

Render modes

In addition to "form" component templates, there are other render modes that allow for different representations of the same component.

The built-in render modes include:

• "form" - The default render to render as a form.
• "html" - Render the data as generic html, instead of a form.

Use form options to set the render mode:

import { Form } from '@formio/js';

const form = new Form(document.getElementById('formio'), 'https://forms.mysite.com/myproject/myform', {
  renderMode: 'html'
});

You can also create your own render modes:

import { Form, Templates } from '@formio/js';

Templates.current = {
  input: {
    myCustomRenderMode: (ctx) => '<div>bar</div>'
  }
};

const form = new Form(document.getElementById('formio'), 'https://forms.mysite.com/myproject/myform', {
  renderMode: 'myCustomRenderMode'
});