While Formie's default templates suit most needs, you can of course roll your own templates, so you have total control over the form, field, layout and more.
We recommend reading the theming overview docs before getting started, for an explanation of template overrides compared to other methods of theming forms.
The great thing about Formie's custom templates is that it doesn't have to be all-or-nothing. You can choose to override a single template, or all. For instance, you might have very specific markup needs to a Dropdown field. You can override just the template for the dropdown field, and nothing else.
To get started, navigate to Formie → Settings → Form Templates and create a new template. Enable the Use Custom Template setting to be able to define a template directory for your custom templates to sit. For example, if your templates exist in templates/_forms, you would enter _forms.
Be sure to select a directory when setting the template path, as there are multiple templates Formie can override. You can look at the directory structure (opens new window) for more.
You can also use the Copy Templates setting when creating, which will copy all of Formie's default templates into the directory you've specified. That way, you're starting off with the templates Formie already uses as a basis for your custom templates.
You can't modify Formie's default Form Templates. Instead, you must create a new Form Template, and ensure your forms use that. This gives you the benefit of being able to easily manage multiple custom templates across your forms.
Before we dive in, it's worth taking the time to understand the structure of how templates go together.
We're using the .html extension here for clarity. You can use .twig or whatever you have set in your defaultTemplateExtensions (opens new window) for the actual files.
form.htmlfield.htmlpage.html_includes/label.htmlsubmit.html...fields/address.htmlagree.htmlcategories.htmldate/_calendar.html_datepicker.html......Let's start with the top-level templates.
Check out the raw templates on Formie's GitHub (opens new window) - they'll be the most up to date.
To override the form template, provide a file named form.html in your template directory.
Field templates have access to the following variables:
| Variable | Description |
|---|---|
form | A Form object, for the form instance this template is for. |
submission | The current Submission object this this form may or may not have. |
renderOptions | A collection of Render Options. |
To override the page template, provide a file named page.html in your template directory.
Field templates have access to the following variables:
| Variable | Description |
|---|---|
form | A Form object that this field belongs to. |
page | A Page object, for the page instance this template is for. |
renderOptions | A collection of Render Options. |
To override the field template, provide a file named field.html in your template directory. This is the wrapper template around all fields. You can also override individual field types' templates, rather than changing the template for every field, regardless of type.
Field templates have access to the following variables:
| Variable | Description |
|---|---|
form | A Form object that this field belongs to. |
field | A Field object, for the field instance this template is for. |
handle | The handle of the field. |
element | The current Submission object this this form may or may not have. |
renderOptions | A collection of Render Options. |
You'll notice the above structure includes the fields/ directory. Inside this directory are a mixture of folders and individual files, each representing a template that you're able to override.
First, you'll need to identify the template's name. It's derived from the PHP class name for the field, converted to a "kebab" string. For easy reference, you can use the below table.
| Class Name | Template |
|---|---|
Address | address.html |
Agree | agree.html |
Calculations | calculations.html |
Categories | categories.html |
Checkboxes | checkboxes.html |
Date | date.html |
Dropdown | dropdown.html |
Email | email.html |
Entries | entries.html |
FileUpload | file-upload.html |
Group | group.html |
Heading | heading.html |
Hidden | hidden.html |
Html | html.html |
MultiLineText | multi-line-text.html |
Name | name.html |
Number | number.html |
Password | password.html |
Payment | payment.html |
Phone | phone.html |
Products | products.html |
Radio | radio.html |
Recipients | recipients.html |
Repeater | repeater.html |
Section | section.html |
Signature | signature.html |
SingleLineText | single-line-text.html |
Summary | summary.html |
Table | table.html |
Tags | tags.html |
Users | users.html |
Variants | variants.html |
Adding a template file in your specified template directory will use that template file over the ones Formie provide.
You might also have noticed we've shown date in a folder. Due to how Twig resolves templates, the below are equivalent:
fields/date.html - Is the same as - fields/date/index.html
For complex fields that have multiple templates, we've used folders to organise multiple templates in a single folder. You're welcome to follow this same pattern, but you're not forced to.
For example, the Date field, has the following templates in a folder:
fields/date/_calendar.htmlfields/date/_datepicker.htmlfields/date/_dropdowns.htmlfields/date/_inputs.htmlfields/date/index.htmlThis is because the date field has many display configurations. If you want to override the templates for this field, you just need to alter the index.html file. You can use the includes (denoted by _), or you don't have to.
You'll have noticed in our preview of the templates' directory, the inclusion of an _includes directory. This houses partial templates that are used throughout the templates. This helps not only with re-use, but keeps things modular, which has a flow-on effect when you want to override just a partial.
The form.html file sets up your form, but also includes other partials like _includes/page-tabs.html, _includes/progress.html and _includes/submit.html. Rather than overriding the form.html file just to alter any one of these partials, you can override just the partial.
For example, let's say we want to override the page tabs of a multi-step form. We could create a file _includes/page-tabs.html and add our content to this template. There's no need to override form.html now!
Formie's templates use a custom Twig function like {{ formieInclude('_includes/page-tabs') }}. This is in contrast to what you might be used to in your own templates, something like {% include '_includes/page-tabs' %}. The drawback with this latter approach is how Formie resolves the template partial. Using {% include %} it will expect to find the template partial relative to the template file you're including it from. Instead, formieInclude() will resolve the template partial to either your overrides' folder, or Formie's default templates.