Skip to main content

Formatting Templates

Formatting templates control how a Freeform form appears on your site. Start with a bundled template, customize a copy, or build your own Twig markup using Freeform's render helpers.

​Render Your First Form

1

Open the form builder and choose a Formatting Template in the form's settings.

2

Save the form, then check its appearance in the builder's Preview tab. Try bundled samples with the Preview-only Formatting Template selector and choose a viewport size. Add your site's CSS or JavaScript under Additional Preview Assets when needed.

3

Add this to the Craft Twig template where the form should appear, replacing contact with your form handle:

{{ freeform.form('contact').render() }}

The form uses the template assigned in the builder. A formatting template can be shared across forms, and changing that assignment does not require editing the page template.

Framework templates need their corresponding CSS on the page. Freeform 5.17+ bundled Tailwind 3 samples include compiled framework CSS through Freeform's asset loading. See the template family's guide below for setup and customization details.

​Choose a Sample Template

Plug-and-playBasic Light, Dark, Floating Labels, Conversational, and Multipage All FieldsGrid & FlexboxUnstyled starters for your own CSSBootstrap 5Light, Dark, and Floating LabelsTailwind 4Light and Dark themes for Tailwind CSSdaisyUI 5Light and Dark themes with daisyUI components

Plug-and-play templates include styling without a framework. Unstyled templates provide a starting layout for your CSS. Framework templates use the framework's classes and require its styles; bundled Tailwind 3 samples supply those styles in Freeform 5.17+.

Tailwind 3 and Foundation 6 templates are deprecated. Their existing references remain available under Tailwind CSS and Foundation.

​Choose a Rendering Approach

ApproachUse it when
Assigned formatting templateYou want a reusable Twig template and a short form embed.
Render helpers in your own markupYou need direct control over the page layout and individual fields.
Headless formsYour front end uses a JavaScript framework or GraphQL.

​Formatting Template with Form RenderRecommended

Use form.render() to render the assigned template. To choose a different formatting template for a particular instance:

{{ freeform.form('contact', {
  formattingTemplate: 'contact.twig'
}).render() }}

Create and register custom templates through Template Manager. Follow Creating a Custom Formatting Template to clone a sample and apply it to your forms.

For changes to classes, attributes, labels, or initial values, use Template Overrides before replacing the template's markup.

​Headless using GraphQL and/or a Javascript framework

Use the Headless Getting Started guide for a JavaScript front end. Dedicated guides cover React, Next.js, Vue, Nuxt, and GraphQL.

For a standalone HTML page on the same origin as Craft, see HTML Embeds.

​Customization & Reference

Custom TemplatesClone a sample template and adapt it for your siteTemplate OverridesSelectors, attributes, values, and add/remove/replace syntaxRendering Forms ManuallyForm tags, rows, fields, buttons, and captcha placementExamples & RecipesSmall, focused patterns for common customizations

​AccessibilityImproved in 5.17+

Freeform's bundled formatting templates include improvements for keyboard navigation and screen readers. The specific improvements vary by template and field type:

  • Accessible choice groups: Tailwind 4 and daisyUI 5 templates use fieldset and legend for Checkboxes, Radios, Opinion Scale, Rating, and Cards fields. This associates the question with its available choices.
  • Linked instructions and errors: Inputs reference their instructions and validation errors through aria-describedby. Invalid inputs use aria-invalid="true", helping screen readers identify fields that need attention.
  • Keyboard-accessible controls: Updated Tailwind templates keep visually hidden choice inputs available to keyboard users and screen readers. Visible focus indicators identify the selected control when navigating with a keyboard.
  • Success and error messages: Success banners use role="status" and error banners use role="alert", giving assistive technologies additional context for submission feedback.
  • Multi-page progress: The current page is identified with aria-current="step" in templates with page progress indicators.
  • File upload feedback: Updated Tailwind 4 upload controls associate their labels with the file input, show keyboard focus, and use a status region for selected-file messages.
  • Table and image markup: Table field column headings use scope="col". The Multipage All Fields review template identifies row headings and provides alternative text for uploaded image previews.
  • Decorative icons: Updated decorative icons are hidden from screen readers so they do not distract from labels and messages.

Most existing sample formatting templates in Freeform 5 retain their original HTML structure to avoid breaking layouts and custom styles. Accessibility changes such as replacing field containers and labels with fieldset and legend will be introduced for these templates in Freeform 6. Newer templates, including Tailwind 4 and daisyUI 5, already use this markup for supported choice fields.

​Focusing Validation Errors

Enable Focus First Error After Submit in the form's processing settings to move keyboard focus to the first visible field with an error after validation fails. If there are no field errors, focus moves to the form's error message.

​Custom Formatting Templates

Existing copies of formatting templates do not automatically receive updated Twig markup or copied styles. Compare your custom template with the latest bundled version and bring across the relevant changes, including supporting CSS.

When customizing, preserve label associations, instruction and error IDs, ARIA attributes, and keyboard focus styles. Prefer Freeform's render helpers where practical, and retain the generated attributes when rendering inputs manually.

These improvements provide a stronger starting point for accessible forms. The finished form's accessibility also depends on its labels, instructions, content, styling, and custom controls.

​Troubleshooting

See Troubleshooting Form Issues for problems with appearance, behavior, or submission. For method and property details, use the Form object and Field object references.

Page Feedback