Configuration
You can customise Formie’s settings using a PHP configuration file. This is optional: each setting has a default, so you only need to include the values you want to change.
To override a setting, create formie.php in your Craft project’s /config directory and return an array of setting names and values. For example, the following will set the Ajax request timeout to 30 seconds:
<?php
return [
'ajaxTimeout' => 30,
];All other settings keep their defaults. Add any further settings you want to change to the same array. The options below explain the available settings and their defaults. You can also manage many of these settings in the control panel under Formie → Settings.
Configuration Options
Sets the fallback API error policies for Mailchimp and Campaign Monitor connections without their own saved choices. Configure each connection under Formie → Integrations → Email Marketing → Provider → Advanced → API Error Handling. Connection choices take precedence over this setting, including values in config/formie.php. Without an override, known subscriber rejections use logWarning, and API rate limits and other errors use failQueue.
Each row contains a severity (rejected, rate_limited or failure) and an action (failQueue, logWarning, logInfo or ignore). A category omitted from a non-empty array uses failQueue.
For connections without saved choices, this fallback skips known subscriber rejections with an informational log while keeping other errors as failures:
'integrationApiErrorHandling' => [
['severity' => 'rejected', 'action' => 'logInfo'],
['severity' => 'rate_limited', 'action' => 'failQueue'],
['severity' => 'failure', 'action' => 'failQueue'],
],The skip actions continue processing without marking the delivery successful. Completed jobs disappear from the queue, so choose logWarning or logInfo if you need a record. ignore omits the policy log entry; normal integration logging is unchanged.
Lists URL query parameters to copy from the page where the form first loads to the completion redirect. Parameters already in the destination URL take priority. Set [] to disable forwarding. Only simple values are copied; nested data and security tokens are excluded.
Lists environment variables that editors may use in reference tokens and $NAME notification settings, for example ['PUBLIC_CONTACT_EMAIL']. Only include variables whose values are safe to display in the intended output. The Variable Picker shows their names, not their values. Visitors cannot read environment variables by submitting $NAME as an answer. See Reference Tokens.
Provides the dedicated key used only for encrypted submission field content. Prefer the FORMIE_ENCRYPTION_KEY environment variable so the key is not committed with project files. Generate and save a key to the project’s configured .env file with php craft formie/encryption/generate-key, or add --stdout when an external deployment or secrets system owns the environment. Keep a recoverable copy and use the same key in every environment that must read copied production submissions. See Content Encryption for setup and environment guidance.
Provides read-only rescue keys while encrypted submission content is moved to the current key. Prefer FORMIE_ENCRYPTION_PREVIOUS_KEYS, supplied as a comma-separated list or JSON array. Remove old keys only after php craft formie/encryption/reencrypt reports that every readable value uses the current key. See Content Encryption for the rotation sequence.
Sets a custom name for the plugin.
Sets the default Formie control panel page when clicking Formie in the main navigation.
For sites upgrading from Formie 3, keeps older APIs and browser events working while you update custom code, as explained in Before Disabling Compatibility Mode.
Allows rendered forms to refresh request-specific values when initialised on statically cached pages. Formie also treats this as enabled when Blitz is installed and enabled.
Restricts which submission methods are available in the form builder: both (default), ajax, or page-reload. Payment integrations that require Ajax still force Ajax when applicable.
Forms
Checks that custom form template paths exist before they are saved.
Sets the default form template handle used for new forms.
Sets a stencil handle to apply automatically when new forms are created without an explicit stencil.
Sets the default email template handle used for new email notifications.
Sets structured defaults applied to new forms and stencils, including default submission status, submission title format, privacy settings, submission method, data retention, file-upload deletion behaviour, and appearance settings. Leave a value empty or null to inherit Formie’s built-in behaviour.
Sets defaults applied when a new email notification is created. Leave a value empty or null to inherit Formie’s built-in behaviour.
Controls default captcha integration states for new forms and stencils. Use captchas[handle] with null to inherit each integration’s global enabled state, or true/false to force enable or disable.
Shows an unload warning when a user changes a front-end form and tries to leave without submitting.
Controls how front-end validation and submit errors are announced to screen readers. Use polite (default), assertive, or off for visual-only errors. Live validation while typing always uses polite announcements; submit-time errors use this setting.
Submits the current page content when a user clicks the Back button on a multi-page form.
Controls whether forms can contain multiple pages in the form builder. When disabled, authors cannot add pages and forms with more than one page cannot be saved.
Sets the timeout in seconds for Ajax requests made by Formie’s front-end JavaScript.
Filters field-mapping options shown in integrations to fields that are usually suitable for the target setting.
Includes draft elements when Formie checks where a form is used.
Includes revision elements when Formie checks where a form is used.
Controls whether Formie’s front-end JavaScript can output console messages.
Controls whether Formie’s log files include what people enter into your forms. Formie logs each submission with its request details, and integration errors with the data that was sent. Those values often explain why a submission failed, so they are logged by default, in production as well as development.
Set this to false for sites that handle sensitive information, such as health or financial details. Every log entry is still written, but each value is replaced with a description of it, so [email protected] appears as <string:18>. Support can still see which fields arrived and which were empty, but not what was entered. Plain-text error messages from providers and exceptions are not changed, and can repeat a submitted value.
Fields with content encryption enabled are always left out of the request details, whatever this setting says. Integration data is masked in the same way for any form that has an encrypted field.
Log files sit outside your submissions, so a form’s data retention settings do not apply to them. Craft keeps the five most recent log files by default.
This setting only covers Formie’s logs. Craft’s own logs also record request details when a warning or error occurs. To remove request details from both, add this to config/app.php:
'components' => [
'log' => [
'monologTargetConfig' => [
'logContext' => false,
],
],
],General Fields
Is an array of field classes that should be disabled and unavailable in the form builder.
Sets the default label position for new forms and fields.
Sets the default instruction position for new forms and fields.
Fields
Sets per-field-type defaults applied when new fields are added to a form. Keys are field class names; values are arrays of setting handles and values. Field types opt in via supportedDefaults(). Leave a value empty or null to inherit Formie’s built-in behaviour. For example, set File Upload, Date, Phone, Agree, Email, Number, element field, and other supported field defaults with their field class names as keys. Custom field types can opt in via Field Defaults.
Allows File Upload fields to use public asset volumes, and controls whether “Public URL” is available as an email summary value. Configure in Settings → Field Types and Restrictions.
Controls whether form editors can enable “Allow Multiple” on Dropdown and element fields using a dropdown display type. When disabled, the setting is hidden in the form builder and existing values are forced off. Configure in Settings → Field Types and Restrictions.
Controls whether form editors can enable the country code selector on Phone Number fields. When disabled, the setting is hidden in the form builder and existing values are forced off. For default-off behaviour on new phone fields without hiding the setting, use Field Defaults (countryEnabled: false). Configure in Settings → Field Types and Restrictions.
Allows form editors to select Template as a Hidden field’s default value source. Configure in Settings → Field Types and Restrictions. When disabled, stored Template fields return an empty value and continue to ignore posted input. Their template source is retained. Choose another source before saving an affected form, or re-enable the capability. Custom Value and references remain available.
Allows form editors to enable Allow Twig on HTML fields. Each field must also opt in. When disabled, HTML fields already configured for Twig produce no output, and new fields cannot opt in. Stored content is retained. Existing fields can turn off Allow Twig before saving, or an administrator can restore the capability. Configure in Settings → Field Types and Restrictions.
Allows sandboxed site-template includes in HTML fields. Requires allowHtmlFieldTwig and the field’s Allow Twig setting. When disabled, includes fail with a Twig sandbox error; ordinary permitted Twig expressions still work. This setting does not enable includes in Hidden fields, PDF filenames or other inline templates. Configure in Settings → Field Types and Restrictions.
Always purifies HTML field output, including output from Twig and included templates, and hides the field’s Purify Content control. Existing per-field preferences are retained but cannot bypass this requirement. When false, each field’s Purify Content setting applies; new HTML fields still default to purification enabled. Configure in Settings → Field Types and Restrictions.
These four controls are site-wide policies, not defaults for new fields. Sites upgrading from Formie 3 start with different values, as explained in Field Templates and HTML Purification. They apply to existing fields, imports, duplicated forms, previews and runtime overrides. Administrators can change them when Craft’s allowAdminChanges is enabled, or developers can set them in config/formie.php. Form groups and field defaults cannot loosen these policies. Review existing Hidden Template fields and HTML fields using Twig, includes or unpurified markup before tightening them, then clear any application or CDN caches containing previously rendered forms. Settings changes do not rewrite already-cached HTML.
Stores field content in large-text database columns for projects that expect very large submission payloads.
Controls whether Formie injects Flatpickr styles for Calendar (Advanced) date fields. Set to false when your project already provides its own Flatpickr stylesheet.
Controls how plain-text input values are handled when HTML is submitted. Use preserve or sanitize.
File Uploads
Limits the number of files awaiting completion for one browser/form instance across all its upload fields. Bound files on incomplete submissions and expired files still waiting for physical cleanup count towards the limit. Successfully finalized uploads no longer count. Use a positive value; increase it for forms that legitimately collect many files.
Limits the combined bytes awaiting completion within the same browser/form instance. This applies alongside the file-count limit, Craft's maximum per-file size and each field's own limits. Removing unused files or completing the submission releases the corresponding budget. Expiry alone does not release storage until cleanup succeeds. Staged capabilities expire within 30 days, or the shorter positive maxIncompleteSubmissionAge, even when incomplete-submission retention is unlimited. This is a per-instance budget, not a server-wide storage quota.
Submissions
Sets the maximum age of incomplete submissions in days before they are deleted by scheduled cleanup. Set to 0 to disable automatic deletion.
For sites upgrading from Formie 2 or 3, keeps Signature images in emails sent before the upgrade loading, as explained in Signature Image URLs.
Enables Craft’s CSRF validation checks for anonymous form submissions. Keep it enabled unless you have a specific headless integration that cannot submit CSRF tokens. Client REST transports should send the CSRF token from session.tokens.csrf in the JSON request body when this setting is enabled.
Sends email notifications through Craft’s queue. This is recommended for production sites so form submissions are not slowed down by email delivery.
Sends integrations through Craft’s queue. This is recommended for production sites so form submissions are not slowed down by third-party APIs.
Allows outbound integration requests to trusted private services, such as a self-hosted CRM. Set this in config/formie.php; values saved through the control panel do not grant private-network access. Entries can be exact hostnames (case-insensitive), individual IPv4 or IPv6 addresses, or CIDR ranges. Wildcards, URLs and port numbers are not supported.
<?php
use craft\helpers\App;
return [
'allowedPrivateIntegrationHosts' => array_values(array_filter(array_map(
'trim',
explode(',', (string)App::env('FORMIE_ALLOWED_PRIVATE_HOSTS')),
))),
];For example, set FORMIE_ALLOWED_PRIVATE_HOSTS=crm.internal.example,10.20.30.40,fd12:3456::/48 in your environment. Prefer an exact host or address over a broad range. This permission applies to all outbound integrations, including Web Request URLs that use submitted field values.
Only private IPv4 networks (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) and IPv6 unique-local addresses (fc00::/7) can be allowed. Loopback, link-local, unspecified, multicast, reserved and IPv4 transition addresses remain blocked, even when listed, as does the AWS service range fd00:ec2::/32. Every DNS answer must be public or explicitly allowed. Requests retain DNS pinning, TLS certificate verification, HTTP/HTTPS on ports 80/443, and disabled redirects and proxies. Public endpoints remain allowed without configuration.
Sets the Craft queue priority for notification and integration jobs.
Retains encrypted diagnostic evidence for completed notification and integration deliveries for this many days. Must be at least 1. Cleanup keeps operation identities so a retry doesn't repeat completed steps. Pending, running and failed deliveries retain their evidence so they can be retried. Diagnostic views report omitted evidence explicitly when a size or checkpoint limit is reached. Downloading a support bundle requires acknowledgement that it can contain personal submission data.
Overrides the OAuth redirect URI for integration connections. When omitted, Formie uses an action URL (actions/formie/integrations/callback). Environment variables are supported.
Controls the dev-mode proxy used for payment webhook and return URLs (for example Mollie webhooks and redirect status pages). When omitted in dev mode, Formie uses https://proxy.verbb.io?return=.... Set to a custom base URL to use your own tunnel/proxy, or set to an empty string to disable the proxy and use local URLs directly. Ignored when Craft dev mode is off. Environment variables are supported.
Limits multi-page form payloads to the current page when processing a page request.
Controls which submissions are saved. The default is all.
Sets how long incomplete submission state can be kept for save-and-resume and front-end submission state.
Sets how many days a Save & Continue link remains valid. The link also stops working if the incomplete submission is removed by its retention settings.
The origins allowed to send requests to Formie from another domain, including GraphQL submissions from a browser, such as ['https://www.example.com']. A request from any other origin is refused, and the error names this setting. Origins must match exactly, so list only the origins your own front-end uses.
Limits anonymous form bootstrap requests within the configured rate window. Set to 0 to disable the limit.
Limits anonymous token-refresh requests and submissions, including GraphQL submissions through a public schema, within the configured rate window. Set to 0 to disable the limit.
Sets the rate-limit window used by anonymous client bootstrap and token-refresh requests.
Sent Notifications
Enables Sent Notifications.
Sets the number of days to keep sent notifications before they are deleted by scheduled cleanup. Set to 0 to disable automatic deletion.
Spam
Manage spam rules under Formie → Spam Protection → Spam Rules on each installation, not in config/formie.php. For sites upgrading from Formie 3, Formie reads the saveSpam, spamLimit, spamEmailNotifications, spamBehaviour, spamKeywords and spamBehaviourMessage settings once to seed those rules, as explained in Local Spam Protection Settings.
Email Notifications
Sends an alert email when an email notification fails to send.
Sets additional email addresses that should receive alert emails. Each entry should be an array with an email key. Environment variables are supported.
Optionally sends alert emails to every user in a Craft user group. Additional alertEmails are still sent when configured. At least one of alertEmails or alertEmailsUserGroup is required when sendEmailAlerts is enabled.
Sets the placeholder used when a field has no submitted value in email output.
PDFs
Sets the paper size for generated PDFs.
Sets the paper orientation for generated PDFs.
Allows generated PDFs to load images and other resources from the listed private or reserved hosts. Public HTTP and HTTPS resources work without configuration. Add only hosts you control and intend PDF templates or rich-text fields to access, using hostnames or IP addresses without a scheme or path.
return [
'pdfTrustedRemoteHosts' => [
'assets.internal.example',
],
];Theme
Sets the default theme configuration used when rendering forms and fields.
Controls whether Formie’s front-end styles use CSS cascade layers, including styles loaded dynamically for fields and integrations. The default is unlayered CSS, so layered resets such as Tailwind’s Preflight do not override Formie’s default theme.
Set this to true to use the formie-base, formie-theme-base and formie-theme layers. Your site controls their order relative to its own styles. For Tailwind, place this declaration at the start of your page’s <head>, before any stylesheets or other style blocks:
<style>
@layer theme, base, formie-base, formie-theme-base, formie-theme, components, utilities;
</style>This lets Tailwind components and utilities override Formie’s layered styles. With useCssLayers set to false, normal unlayered Formie declarations take precedence over normal layered utilities; use unlayered custom CSS or opt into layers when you want utility classes to override the default theme.
Captchas
For sites upgrading from Formie 3, Formie reads this setting once to move CAPTCHA providers into Formie → Spam Protection → CAPTCHAs, as explained in Local Spam Protection Settings.
Export
Sets the default folder used by form export console commands.
Alerts Configuration
Supply additional email addresses to receive alert notifications, and optionally set alertEmailsUserGroup to a Craft user group UID to send alerts to every user in that group.
'alertEmails' => [
['email' => '[email protected]'],
['email' => '$FORMIE_ALERT_EMAIL'],
],
'alertEmailsUserGroup' => 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',Theme Configuration
Supply a nested array for the configuration forms and fields should use when rendering.
'themeConfig' => [
'form' => [
'attributes' => [
'class' => 'contact-form',
],
],
'field' => [
'attributes' => [
'class' => 'contact-form-field',
],
],
],Continue reading Theme Config for more.
Rich Text Configuration
Formie uses rich-text fields for several form, notification, and field settings. You can control the toolbar buttons and visible rows for those fields by adding a rich-text.json file to a formie folder in your /config directory.
{
"forms": {
"errorMessage": {
"buttons": ["bold"],
"rows": 3
}
}
}This changes the forms.errorMessage rich-text field so it only shows the Bold button and uses three rows.
The default rich-text config is:
{
"forms": {
"successMessage": {
"buttons": ["bold", "italic", "variableTag"],
"rows": 3
},
"errorMessage": {
"buttons": ["bold", "italic"],
"rows": 3
},
"requireUserMessage": {
"buttons": ["bold", "italic"],
"rows": 3
},
"scheduleFormPendingMessage": {
"buttons": ["bold", "italic"],
"rows": 3
},
"scheduleFormExpiredMessage": {
"buttons": ["bold", "italic"],
"rows": 3
},
"limitSubmissionsMessage": {
"buttons": ["bold", "italic"],
"rows": 3
},
"limitSubmissionsIpAddressMessage": {
"buttons": ["bold", "italic"],
"rows": 3
}
},
"fields": {
"agree": {
"buttons": ["bold", "italic", "link"],
"rows": 3
},
"instructions": {
"buttons": ["bold", "italic", "link"],
"rows": 4
},
"builderNote": {
"buttons": ["bold", "italic", "link"],
"rows": 3
},
"question": {
"buttons": ["bold", "italic", "link", "unordered-list", "ordered-list"],
"rows": 4
},
"content": {
"buttons": ["bold", "italic", "underline", "link", "unordered-list", "ordered-list", "h2", "h3", "paragraph"],
"rows": 8
},
"calculations": {
"buttons": ["variableTag"],
"rows": 3
}
},
"notifications": {
"content": {
"buttons": ["bold", "italic", "variableTag"]
}
}
}Available Buttons
As shown above, your config can provide an array of button names to include in the rich-text field interface.
| Button | Description |
|---|---|
bold | Allows text to be bold. |
italic | Allows text to be italic. |
underline | Allows text to be underlined. |
strikethrough | Allows text to have a strikethrough. |
h1–h6 | Applies the corresponding heading level. |
paragraph | Allows Paragraph formatting. |
blockquote | Allows blockquote formatting. |
ordered-list | Allows ordered lists. |
unordered-list | Allows unordered lists. |
code | Allows inline code formatting. |
code-block | Allows code-block formatting. |
subscript | Applies subscript formatting. |
superscript | Applies superscript formatting. |
small-caps | Applies small caps through TipTap's TextStyle mark. |
highlight | Highlights text. |
hr | Inserts a horizontal rule. |
line-break | Inserts a hard line break. |
link | Allows links. |
table | Inserts a table. |
align-left | Allows left alignment. |
align-center | Allows center alignment. |
align-right | Allows right alignment. |
align-justify | Allows justified alignment. |
clear-format | Clears formatting. |
undo | Undoes the latest change. |
redo | Redoes the latest undone change. |
font-family | Opens the font-family TextStyle menu. |
font-size | Opens the font-size TextStyle menu. |
text-color | Opens text and background color TextStyle menus. |
line-height | Opens the line-height TextStyle menu. |
variableTag | Allows variable tags where the field supports them. |
{
"buttons": ["bold", "italic", "link", "variableTag"],
"rows": 4
}The fields.content key controls the Rich Text cosmetic field toolbar and height.
The fields.builderNote key controls the Editor Note rich-text field on the field editor Advanced tab.
Text Styles
Font family, font size, text color, background color, line height, and small caps are built into Formie's rich-text schema. They are opt-in toolbar controls, so adding them does not change existing Formie toolbars:
{
"fields": {
"content": {
"buttons": [
"font-family",
"font-size",
"bold",
"italic",
"small-caps",
"text-color",
"line-height",
"link"
],
"textStyleOptions": {
"fontFamilies": [
{ "label": "Default font", "value": null },
{ "label": "Brand Sans", "value": "Brand Sans, sans-serif" },
{ "label": "Georgia", "value": "Georgia, serif" }
],
"fontSizes": [
{ "label": "Default", "value": null },
{ "label": "Small", "value": "14px" },
{ "label": "Body", "value": "16px" },
{ "label": "Large", "value": "24px" }
]
}
}
}
}Omit textStyleOptions to use Plugin Kit's default choices. Any option family you provide replaces that family of defaults for the configured Formie field.
Extending the Rich-text Editor
Formie does not register project-specific TipTap nodes, marks, or extensions by default, but modules and plugins can register them before the form builder mounts. For a complete Formie example—including matching PHP and JavaScript extensions, a toolbar control, and asset loading—see TipTap Extensions.
HTML Editor Configuration
HTML cosmetic fields use a syntax-highlighted code editor in the form builder. You can control editor height and behaviour by adding an html.json file to a formie folder in your /config directory.
{
"fields": {
"html": {
"rows": 16,
"tabSize": 4,
"lineNumbers": true,
"language": "html"
}
}
}Available Settings
| Setting | Description |
|---|---|
rows | Minimum visible editor rows. |
tabSize | Number of spaces inserted when pressing Tab. |
lineNumbers | Whether to show a line number gutter. |
language | Code editor language mode. Currently supports html or text. |