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.
For project config, environment variables, and control panel settings across staging and production, see Project config, environment, and control panel settings.
Configuration Options
Type: array · Default: []
Adds exact external origins permitted for completion redirects, for example ['https://partner.example.com']. Configured Craft site origins and safe relative paths are already allowed. Scheme, host and port must match. See Completion and Redirects.
Type: array · Default: ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content']
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.
Type: array · Default: []
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.
Type: string · Default: 'Formie'
Sets a custom name for the plugin.
Type: string · Default: 'forms'
Sets the default Formie control panel page when clicking Formie in the main navigation.
Type: bool · Default: true
Enables compatibility shims for older Formie APIs during an upgrade.
Type: bool · Default: false
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.
Type: string · Default: self::ALLOWED_SUBMIT_METHODS_BOTH
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
validateCustomTemplates
Type: bool · Default: true
Checks that custom form template paths exist before they are saved.
defaultFormTemplate
Type: string · Default: ''
Sets the default form template handle used for new forms.
defaultFormStencil
Type: string · Default: ''
Sets a stencil handle to apply automatically when new forms are created without an explicit stencil.
defaultEmailTemplate
Type: string · Default: ''
Sets the default email template handle used for new email notifications.
formDefaults
Type: array · Default: []
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.
notificationDefaults
Type: array · Default: []
Sets defaults applied when a new email notification is created. Leave a value empty or null to inherit Formie’s built-in behaviour.
integrationDefaults
Type: array · Default: []
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.
enableUnloadWarning
Type: bool · Default: true
Shows an unload warning when a user changes a front-end form and tries to leave without submitting.
errorAriaLive
Type: string · Default: self::ERROR_ARIA_LIVE_POLITE
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.
enableBackSubmission
Type: bool · Default: true
Submits the current page content when a user clicks the Back button on a multi-page form.
enableMultiPageForms
Type: bool · Default: true
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.
ajaxTimeout
Type: int · Default: 10
Sets the timeout in seconds for Ajax requests made by Formie’s front-end JavaScript.
filterIntegrationMapping
Type: bool · Default: true
Filters field-mapping options shown in integrations to fields that are usually suitable for the target setting.
includeDraftElementUsage
Type: bool · Default: false
Includes draft elements when Formie checks where a form is used.
includeRevisionElementUsage
Type: bool · Default: false
Includes revision elements when Formie checks where a form is used.
outputConsoleMessages
Type: bool · Default: true
Controls whether Formie’s front-end JavaScript can output console messages.
General Fields
disabledFields
Type: array · Default: []
Is an array of field classes that should be disabled and unavailable in the form builder.
defaultLabelPosition
Type: string · Default: AboveInput::class
Sets the default label position for new forms and fields.
defaultInstructionsPosition
Type: string · Default: AboveInput::class
Sets the default instruction position for new forms and fields.
Fields
fieldDefaults
Type: array · Default: []
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.
allowPublicVolumes
Type: bool · Default: true
Allows File Upload fields to use public asset volumes, and controls whether “Public URL” is available as an email summary value. Configure in Settings → Fields.
allowMultiSelectDropdowns
Type: bool · Default: true
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 → Fields.
allowPhoneCountrySelector
Type: bool · Default: true
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 → Fields.
enableLargeFieldStorage
Type: bool · Default: false
Stores field content in large-text database columns for projects that expect very large submission payloads.
includeFlatpickrCss
Type: bool · Default: true
Controls whether Formie injects Flatpickr styles for Calendar (Advanced) date fields. Set to false when your project already provides its own Flatpickr stylesheet.
plainTextHtmlSanitizationMode
Type: string · Default: self::PLAIN_TEXT_HTML_SANITIZATION_MODE_PRESERVE
Controls how plain-text input values are handled when HTML is submitted. Use preserve or sanitize.
File Uploads
maxStagedUploadFiles
Type: int · Default: 50
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.
maxStagedUploadBytes
Type: int · Default: 67108864 (64 MiB)
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
maxIncompleteSubmissionAge
Type: int · Default: 30
Sets the maximum age of incomplete submissions in days before they are deleted by scheduled cleanup. Set to 0 to disable automatic deletion.
allowLegacySignatureImageUrls
Type: bool · Default: true
Allows previously sent unsigned Formie 2 and Formie 3 Signature image URLs to continue loading for submissions explicitly marked as legacy during the upgrade. New Formie 4 submissions always use signed, non-expiring, exact-value image URLs. Set this to false when historical email images no longer need to load.
enableCsrfValidationForGuests
Type: bool · Default: true
Enables Craft’s CSRF validation checks for anonymous form submissions.
useQueueForNotifications
Type: bool · Default: true
Sends email notifications through Craft’s queue. This is recommended for production sites so form submissions are not slowed down by email delivery.
useQueueForIntegrations
Type: bool · Default: true
Sends integrations through Craft’s queue. This is recommended for production sites so form submissions are not slowed down by third-party APIs.
queuePriority
Type: int|null · Default: null
Sets the Craft queue priority for notification and integration jobs.
deliveryEvidenceRetentionDays
Type: int · Default: 30
Retains encrypted diagnostic evidence for completed notification and integration deliveries for this many days. Must be at least 1. Cleanup keeps operation identities and audit decisions to prevent accidental replay. Pending, running, uncertain and retryable failed deliveries retain their evidence for reconciliation. 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.
redirectUri
Type: string|null · Default: null
Overrides the OAuth redirect URI for integration connections. When omitted, Formie uses an action URL (actions/formie/integrations/callback). Environment variables are supported.
paymentWebhookProxyUrl
Type: string|null · Default: null
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.
setOnlyCurrentPagePayload
Type: bool · Default: false
Limits multi-page form payloads to the current page when processing a page request.
submissionsBehaviour
Type: string|array · Default: 'all'
Controls which submissions are saved. The default is all.
submissionStateRetentionDays
Type: int · Default: 30
Sets how long incomplete submission state can be kept for save-and-resume and front-end submission state.
saveResumeTokenTtlDays
Type: int · Default: 14
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.
anonymousClientBootstrapRateLimit
Type: int · Default: 30
Limits anonymous client bootstrap requests within the configured rate window. Set to 0 to disable the limit.
anonymousClientRefreshRateLimit
Type: int · Default: 120
Limits anonymous token-refresh requests within the configured rate window. Set to 0 to disable the limit.
anonymousClientRateWindowSeconds
Type: int · Default: 60
Sets the rate-limit window used by anonymous client bootstrap and token-refresh requests.
Security-Sensitive Settings
- Keep
allowedGraphqlOriginsas narrow as possible when using headless forms. Avoid wildcard or broad origins when credentialed requests are allowed. - Public GraphQL schemas should only include the Formie form and submission scopes required by the front-end consuming them.
- Keep
enableCsrfValidationForGuestsenabled unless you have a specific headless integration that cannot submit CSRF tokens. Client REST transports should send the CSRF token fromsession.tokens.csrfin the JSON request body when this setting is enabled. - Store integration API keys and secrets in environment variables (for example
$STRIPE_SECRET_KEY) rather than plaintext in the database when possible. Formie persists integration settings as JSON informie_integrations; values that use Craft's env syntax are resolved when settings are loaded and are not stored in project config exports.
Sent Notifications
sentNotifications
Type: bool · Default: true
Enables Sent Notifications.
maxSentNotificationsAge
Type: int · Default: 30
Sets the number of days to keep sent notifications before they are deleted by scheduled cleanup. Set to 0 to disable automatic deletion.
Spam
saveSpam
Type: bool · Default: true
Saves spam submissions to the database.
spamLimit
Type: int · Default: 500
Limits how many saved spam submissions are kept.
spamEmailNotifications
Type: bool · Default: false
Allows submissions marked as spam to still trigger email notifications.
spamBehaviour
Type: string · Default: self::SPAM_BEHAVIOUR_SUCCESS
Controls what the user sees when a spam submission is detected. Use showSuccess or showMessage.
spamKeywords
Type: string · Default: ''
Marks a submission as spam when the submitted content matches the configured keywords.
spamBehaviourMessage
Type: string · Default: ''
Sets the message shown when spamBehaviour is showMessage. HTML and Markdown are supported.
Email Notifications
sendEmailAlerts
Type: bool · Default: false
Sends an alert email when an email notification fails to send.
alertEmails
Type: array|null · Default: null
Sets additional email addresses that should receive alert emails. Each entry should be an array with an email key. Environment variables are supported.
alertEmailsUserGroup
Type: string|null · Default: null
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.
emptyValuePlaceholder
Type: string · Default: 'No response.'
Sets the placeholder used when a field has no submitted value in email output.
PDFs
pdfPaperSize
Type: string · Default: 'letter'
Sets the paper size for generated PDFs.
pdfPaperOrientation
Type: string · Default: 'portrait'
Sets the paper orientation for generated PDFs.
Theme
themeConfig
Type: array · Default: []
Sets the default theme configuration used when rendering forms and fields.
useCssLayers
Type: bool · Default: false
Outputs Formie’s front-end CSS inside a CSS cascade layer.
Captchas
captchas
Type: array · Default: []
Stores project-config-backed captcha settings.
Export
defaultExportFolder
Type: string · Default: '@storage/formie-export'
Sets the default folder used by form export console commands.
Form Groups (Project Config)
Form groups are managed in the control panel under Formie → Settings → Form Groups, but their definitions are stored in project config under formie.formGroups.{uid}:
formie:
formGroups:
7f3e2a1b-0000-4000-8000-000000000001:
name: Marketing
handle: marketing
sortOrder: 1Each entry contains name, handle, and sortOrder. Individual forms store an optional groupId in the database; that ID is resolved from the project-config group UID on each environment.
See Form Groups for control panel behaviour.
Reports (Project Config)
Report definitions and scheduled delivery settings are stored in project config:
formie:
reports:
a1b2c3d4-0000-4000-8000-000000000001:
name: Weekly Enquiries
handle: weeklyEnquiries
sortOrder: 1
# filters, columns, display, and export settings…
scheduledReports:
b2c3d4e5-0000-4000-8000-000000000002:
name: Monday summary
enabled: true
delivery:
frequency: weekly
weekday: 1
hour: 8
recipients:
- [email protected]Each report entry stores its analytical settings. Scheduled report entries store delivery configuration; the linked report is resolved by UID in each environment. Database-only fields such as lastSentAt are stored in the database only.
See Reports and Scheduled reports for control panel behaviour and cron setup.
Control Panel
You can also manage many configuration settings through the control panel by visiting Formie → Settings. Form, field, and notification defaults are managed on the dedicated Defaults settings page.
Permissions
Formie registers Craft user permissions under Settings → Users → {user group} → Formie. For the Reports section, assign:
| Permission | Purpose |
|---|---|
| Access reports | Open Formie → Reports and run saved reports |
| Manage reports | Create, edit, and delete reports; export data |
| Manage scheduled reports | Configure delivery under Settings → Scheduled Reports and on a report’s Scheduled tab |
Users with Export submissions can export from reports without Manage reports.
To restrict settings access, assign individual page permissions such as Forms settings or Email notifications settings. Leave Access all settings unselected for these roles; that permission grants access to every settings page. Administrators retain access to all settings.
Scheduled email delivery requires a cron schedule. Use ./craft formie/cron/run (recommended) or ./craft formie/reports/run-scheduled. See Scheduled reports.
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. |