Configuration

Create a formie.php file under your /config directory with the following options available to you. You can also use multi-environment options to change these settings per environment.

The example below shows the defaults already used by Formie, so you only need to add the settings you want to change.

<?php

return [
    '*' => [
        'pluginName' => 'Formie',
        'defaultPage' => 'forms',
        'compatibilityMode' => true,
        'staticCacheRefreshOnLoad' => false,

        // Forms
        'validateCustomTemplates' => true,
        'defaultFormTemplate' => '',
        'defaultEmailTemplate' => '',
        'enableUnloadWarning' => true,
        'enableBackSubmission' => true,
        'ajaxTimeout' => 10,
        'filterIntegrationMapping' => true,
        'includeDraftElementUsage' => false,
        'includeRevisionElementUsage' => false,
        'outputConsoleMessages' => true,

        // General Fields
        'disabledFields' => [],
        'defaultLabelPosition' => \verbb\formie\positions\AboveInput::class,
        'defaultInstructionsPosition' => \verbb\formie\positions\AboveInput::class,

        // Fields
        'defaultFileUploadVolume' => '',
        'allowPublicVolumes' => true,
        'defaultDateDisplayType' => 'calendar',
        'defaultDateValueOption' => '',
        'defaultDateTime' => null,
        'enableLargeFieldStorage' => false,
        'plainTextHtmlSanitizationMode' => 'preserve',

        // Submissions
        'maxIncompleteSubmissionAge' => 30,
        'enableCsrfValidationForGuests' => true,
        'useQueueForNotifications' => true,
        'useQueueForIntegrations' => true,
        'queuePriority' => null,
        'setOnlyCurrentPagePayload' => false,
        'submissionsBehaviour' => 'all',
        'submissionStateRetentionDays' => 30,
        'saveResumeTokenTtlDays' => 14,
        'maxSavedDraftsPerSession' => 10,
        'anonymousClientBootstrapRateLimit' => 30,
        'anonymousClientRefreshRateLimit' => 120,
        'anonymousClientRateWindowSeconds' => 60,

        // Sent Notifications
        'sentNotifications' => true,
        'maxSentNotificationsAge' => 30,

        // Spam
        'saveSpam' => true,
        'spamLimit' => 500,
        'spamEmailNotifications' => false,
        'spamBehaviour' => 'showSuccess',
        'spamKeywords' => '',
        'spamBehaviourMessage' => '',

        // Email Notifications
        'sendEmailAlerts' => false,
        'alertEmails' => null,
        'emptyValuePlaceholder' => 'No response.',

        // PDFs
        'pdfPaperSize' => 'letter',
        'pdfPaperOrientation' => 'portrait',

        // Theme
        'themeConfig' => [],
        'useCssLayers' => false,

        // Captchas
        'captchas' => [],

        // Export
        'defaultExportFolder' => '@storage/formie-export',
    ],
];

Configuration options

• pluginName sets a custom name for the plugin.
• defaultPage sets the default Formie control panel page when clicking Formie in the main navigation.
• compatibilityMode enables compatibility shims for older Formie APIs during an upgrade.
• staticCacheRefreshOnLoad allows rendered forms to refresh request-specific values when initialized on statically cached pages. Formie also treats this as enabled when Blitz is installed and enabled.

Forms

• validateCustomTemplates checks that custom form template paths exist before they are saved.
• defaultFormTemplate sets the default form template handle used for new forms.
• defaultEmailTemplate sets the default email template handle used for new email notifications.
• enableUnloadWarning shows an unload warning when a user changes a front-end form and tries to leave without submitting.
• enableBackSubmission submits the current page content when a user clicks the Back button on a multi-page form.
• ajaxTimeout sets the timeout in seconds for Ajax requests made by Formie’s front-end JavaScript.
• filterIntegrationMapping filters field-mapping options shown in integrations to fields that are usually suitable for the target setting.
• includeDraftElementUsage includes draft elements when Formie checks where a form is used.
• includeRevisionElementUsage includes revision elements when Formie checks where a form is used.
• outputConsoleMessages controls whether Formie’s front-end JavaScript can output console messages.

General Fields

• disabledFields is an array of field classes that should be disabled and unavailable in the form builder.
• defaultLabelPosition sets the default label position for new forms and fields.
• defaultInstructionsPosition sets the default instruction position for new forms and fields.

Fields

• defaultFileUploadVolume sets the asset volume used as the default for new File Upload fields. Use the folder:uid format.
• allowPublicVolumes allows File Upload fields to use public asset volumes.
• defaultDateDisplayType sets the default display type for new Date fields. Use calendar, dropdowns, or inputs.
• defaultDateValueOption sets the default value mode for new Date fields. Use today or date.
• defaultDateTime sets the default date when defaultDateValueOption is date.
• enableLargeFieldStorage stores field content in large-text database columns for projects that expect very large submission payloads.
• plainTextHtmlSanitizationMode controls how plain-text input values are handled when HTML is submitted. Use preserve or sanitize.

Submissions

• maxIncompleteSubmissionAge sets the maximum age of incomplete submissions in days before they are deleted during garbage collection. Set to 0 to disable automatic deletion.
• enableCsrfValidationForGuests enables Craft’s CSRF validation checks for anonymous form submissions.
• useQueueForNotifications sends email notifications through Craft’s queue. This is recommended for production sites so form submissions are not slowed down by email delivery.
• useQueueForIntegrations sends integrations through Craft’s queue. This is recommended for production sites so form submissions are not slowed down by third-party APIs.
• queuePriority sets the Craft queue priority for notification and integration jobs.
• setOnlyCurrentPagePayload limits multi-page form payloads to the current page when processing a page request.
• submissionsBehaviour controls which submissions are saved. The default is all.
• submissionStateRetentionDays sets how long incomplete submission state can be kept for save-and-resume and front-end submission state.
• saveResumeTokenTtlDays sets how long a save-and-resume token remains valid.
• maxSavedDraftsPerSession limits how many saved drafts can be created in one browser session.
• anonymousClientBootstrapRateLimit limits anonymous client bootstrap requests within the configured rate window. Set to 0 to disable the limit.
• anonymousClientRefreshRateLimit limits anonymous token-refresh requests within the configured rate window. Set to 0 to disable the limit.
• anonymousClientRateWindowSeconds sets the rate-limit window used by anonymous client bootstrap and token-refresh requests.

Security-sensitive runtime settings

• Keep allowedGraphqlOrigins as narrow as possible when using headless/runtime 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 enableCsrfValidationForGuests enabled unless you have a specific headless/runtime integration that cannot submit CSRF tokens.

Sent Notifications

• sentNotifications enables Sent Notifications.
• maxSentNotificationsAge sets the number of days to keep sent notifications before they are deleted permanently. Set to 0 to disable automatic deletion.

Spam

• saveSpam saves spam submissions to the database.
• spamLimit limits how many saved spam submissions are kept.
• spamEmailNotifications allows submissions marked as spam to still trigger email notifications.
• spamBehaviour controls what the user sees when a spam submission is detected. Use showSuccess or showMessage.
• spamKeywords marks a submission as spam when the submitted content matches the configured keywords.
• spamBehaviourMessage sets the message shown when spamBehaviour is showMessage. HTML and Markdown are supported.

Email Notifications

• sendEmailAlerts sends an alert email when an email notification fails to send.
• alertEmails sets the name and email address pairs that should receive alert emails.
• emptyValuePlaceholder sets the placeholder used when a field has no submitted value in email output.

PDFs

• pdfPaperSize sets the paper size for generated PDFs.
• pdfPaperOrientation sets the paper orientation for generated PDFs.

Theme

• themeConfig sets the default theme configuration used when rendering forms and fields.
• useCssLayers outputs Formie’s front-end CSS inside a CSS cascade layer.

Captchas

• captchas stores project-config-backed captcha settings.

Export

• defaultExportFolder sets the default folder used by form export console commands.

Control Panel

You can also manage many configuration settings through the control panel by visiting Formie → Settings.

Alerts Configuration

Supply a nested array for the name and email of each contact to receive alert notifications. The first value should contain the name, and the second value should contain the email address.

'alertEmails' => [
    ['Primary Name', '[email protected]'],
    ['Secondary Admin Name', '[email protected]'],
],

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": {
        "submitActionMessage": {
            "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
        },
        "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.

{
    "buttons": ["bold", "italic", "link", "variableTag"],
    "rows": 4
}