Reference tokens

Reference tokens are Formie's variable syntax for inserting dynamic submission, form, site, and user values into settings and content. They resolve when Formie processes a submission — not when your Twig template renders.

Use the variable picker in the control panel wherever it is available, or build the same tokens from Twig or PHP when you override settings in templates.

Where tokens are used

Reference tokens appear anywhere Formie parses variable-aware content, including:

• Submit action messages, error messages, and other form rich-text settings
• Email notifications — subject, body, recipients
• PDF templates
• Integration mapping fields (CRM, payments, messaging, and so on)
• Hidden field default values, calculations formulas, client event payloads, and spam keyword lines

How tokens work

A token is a braced string Formie stores in settings, then resolves against the current submission:

{target:identifier}

Examples:

Formie resolves tokens in stored content at submit time (or when previewing with sample submission data in the control panel). Twig is not evaluated inside submit action messages, notification bodies, or similar settings.

That means these do not work in those settings:

• Twig output syntax such as {{ submission.uid }}
• Legacy flat tokens such as {submissionUid} or {field:myHandle}

Use reference tokens instead — the same strings the variable picker inserts.

Inline defaults

Add a fallback when the resolved value is empty:

{submission:uid|pending}

Transforms and metadata

Some contexts support transforms and extra metadata on the token body:

{timestamp;transform=format;preset=isoDate}
{field:a1b2c3:email;scope=all}

The variable picker configures these for you. When building tokens manually, match the picker output. See Calculations for transform examples on field references.

Built-in tokens

These tokens are available on every form. In the control panel, open the variable picker to insert them. From Twig, use craft.formie.ref() with the target and identifier shown in the Twig column.

Summary selectors

Form

Submission

Site

System

Current user

Values reflect the logged-in user when the submission is made, or the submission's linked user when applicable.

Current date/time

Use transform metadata for formatted output — for example {timestamp;transform=format;preset=isoDate}. The picker exposes the available format options.

Environment

When Craft environment variables are available, the picker lists {env:KEY} tokens for each key. Build them from Twig with:

{{ craft.formie.ref('env', 'MY_ENV_KEY') }}

Field tokens

Field values use a stable field reference, not the field handle. Each field on a form has a reference ID that stays consistent when the handle changes.

{# Resolves the field handle to the stable reference token #}
{{ craft.formie.refField(form, 'email') }}

{# Nested or composite field selector #}
{{ craft.formie.refField(form, 'address', 'city') }}

Some fields expose multiple selectors (for example Name, Address, Date/Time, Table, and Repeater columns). Use the variable picker on that field in the form builder to see which selectors are available.

Custom variables

Register project-specific variables with {custom:handle} tokens. See Custom variable sources.

{{ craft.formie.ref('custom', 'acme_campaign') }}

Building tokens from Twig

Use craft.formie.ref() and craft.formie.refField() when overriding form settings in templates — for example a dynamic submit action message:

{% set form = craft.formie.forms.handle('contactForm').one() %}

{% do form.setSettings({
    submitActionMessage: 'Thanks! Your reference is ' ~ craft.formie.ref('submission', 'uid'),
}) %}

{{ craft.formie.renderForm(form) }}

craft.formie.ref(target, identifier, selector, options) parameters:

Concatenate the returned string with other text using Twig's ~ operator.

Resolving tokens in Twig templates

When you already have a submission in a Twig template and want the resolved value (not the token string), use:

{{ craft.formie.parseContent('{submission:uid}', submission) }}
{{ craft.formie.parseValue('{field:a1b2c3}', submission) }}

These run reference resolution immediately in the current request — unlike tokens stored in form settings, which resolve at submit time.

PHP

use verbb\formie\helpers\References;

// Build a token
References::token('submission', 'uid');
References::field('a1b2c3', 'email');
References::token('field', 'a1b2c3', 'email', ['scope' => 'all']);

// Resolve a token against a submission
References::parseContent('{submission:uid}', $submission);
References::parseValue('{field:a1b2c3}', $submission);