# Form Templates

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**](https://github.com/formio/bootstrap3)
* United States Web Design System (USWDS) - [**https://github.com/formio/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**](https://github.com/DigitalPatterns/formio-gds-template)
* Bulma - [**https://github.com/formio/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](https://github.com/formio/bootstrap) and [the Form.io USWDS template.](https://github.com/formio/uswds)

## Framework Templates

By default, the @formio/js renderer uses [the Form.io Bootstrap 5-based template.](https://github.com/formio/bootstrap) To use another template, import the template object and pass it as an argument to `Formio.use`.

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

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

```javascript
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.

```javascript
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;
```

```javascript
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<br>

  ```javascript
  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"`)<br>

  ```javascript
  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"` )<br>

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

{% embed url="<https://jsfiddle.net/brendanbond/6q851ytg/9/>" %}

## 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](https://help.form.io/developers/form-renderer#form-renderer-options) to set the render mode:

```javascript
import { Form } from 'formiojs';

const form = new Form(document.getElementById('formio'), 'https://examples.form.io/example', {
  renderMode: 'html'
});
```

You can also create your own render modes:

```javascript
import { Form, Templates } from 'formiojs';

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

const form = new Form(document.getElementById('formio'), 'https://examples.form.io/example', {
  renderMode: 'myCustomRenderMode'
});
```