The Form.io Standard Template

Previously, there were two options for customizing the look and feel of your forms when they were rendered in your application.

1. You could use the default Bootstrap 5-based template and override Bootstrap directly in your application. This is a great option for Bootstrap-based applications, but forces applications that are not based on Bootstrap to include it as a dependency and also introduces the possibility of CSS collisions.

2. You could use the default Bootstrap 5-based template as a guide to writing your own template. This can be difficult; the component templates are written in an older templating syntax, and writing the DOM structure for components can require a deep knowledge of Form.io internals (e.g. ref attributes).

The Form.io Standard Template makes customizing the look and feel of the forms in your application easier by providing a default underlying HTML markup structure for each built-in component and exposing APIs that allow you to inject custom CSS class names into each component's constituent elements using JSON. This allows a more seamless integration with libraries like TailwindCSS without having to create an entire template from scratch.

Getting Started

The Form.io Standard Template is available as an npm package.

npm install @formio/standard-template

The library exposes a function that you can use as a Form.io module.

import { Formio } from '@formio/js';
import { standardTemplate, BOOTSTRAP_EXAMPLE } from '@formio/standard-template';

Formio.use(standardTemplate(BOOTSTRAP_EXAMPLE));
Formio.createForm(document.getElementById('formio'), 'https://examples.form.io/example');

How It Works

The Form.io Standard Template is a template - a collection of pre-compiled functions that return DOM strings - with no associated CSS classes. The CSS class names are provided by the user in the form of a JSON object that contains each component template along with each component template's constituent elements. For example, the "input" template includes things like the actual input element, the character count (for input-based components that have character count enabled), and the prefix/suffix (for input-based components with prefixes or suffixes enabled).

{
  /* ... */
  // the input component template
  "input": {
    // the "form" render mode
    "form": {
      // the input element and its CSS class names
      "input": ["form-control"],
      // the suffix and prefix
      "suffix": ["input-group-text"],
      "prefix": ["input-group-text"],
    /* ... */
    }
  }
  /* ... */
}
    

We've included a BOOSTRAP_EXAMPLE constant with the beta version of the Form.io Standard Template that you can use as a guide - it is a Standard Template-compatible JSON object that contains our Bootstrap 5 template class names.