We're off to DotAll 2022 in Brooklyn NY (plus a little extra sightseeing time). Our support will be limited.

GraphQL#

Formie supports accessing Form and Submission objects via GraphQL. Be sure to read about Craft's GraphQL support (opens new window).

Have a look at our headless Formie demo (opens new window) to get a feel for what's possible with GraphQL.

Forms#

Example#

{
    formieForm (handle: "contactForm") {
        title
        handle

        settings {
            errorMessageHtml
        }
        
        pages {
            name

            rows {
                rowFields {
                    name
                    handle
                    type
                    displayName

                    ... on Field_Name {
                        firstNameLabel
                        firstNameRequired
                        lastNameLabel
                        lastNameRequired
                    }

                    ... on Field_Email {
                        placeholder
                    }
                }
            }
        }
    }
}
{
    "data": {
        "formieForm": {
            "title": "Contact Form",
            "handle": "contactForm",
            "settings": {
                "errorMessageHtml": "Couldn’t save submission due to errors."
            },
            "pages": [
                {
                    "name": "Page 1",
                    "rows": [
                        {
                            "rowFields": [
                                {
                                    "name": "Your Name",
                                    "handle": "yourName",
                                    "type": "verbb\\formie\\fields\\formfields\\Name",
                                    "displayName": "Name",
                                    "firstNameLabel": "First Name",
                                    "firstNameRequired": true,
                                    "lastNameLabel": "Last Name",
                                    "lastNameRequired": true
                                }
                            ]
                        },
                        {
                            "rowFields": [
                                {
                                    "name": "Email Address",
                                    "handle": "emailAddress",
                                    "type": "verbb\\formie\\fields\\formfields\\Email",
                                    "displayName": "Email",
                                    "placeholder": "eg. psherman@wallaby.com"
                                }
                            ]
                        },
                        {
                            "rowFields": [
                                {
                                    "name": "Message",
                                    "handle": "message",
                                    "type": "verbb\\formie\\fields\\formfields\\MultiLineText",
                                    "displayName": "MultiLineText"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    }
}

The formieForms query#

This query is used to query for Form objects. You can also use the singular formieForm to fetch a single form.

ArgumentTypeDescription
id[QueryArgument]Narrows the query results based on the elements’ IDs.
uid[String]Narrows the query results based on the elements’ UIDs.
archivedBooleanNarrows the query results to only elements that have been archived.
trashedBooleanNarrows the query results to only elements that have been soft-deleted.
uniqueBooleanDetermines whether only elements with unique IDs should be returned by the query.
title[String]Narrows the query results based on the elements’ titles.
searchStringNarrows the query results to only elements that match a search query.
relatedTo[Int]Narrows the query results to elements that relate to any of the provided element IDs. This argument is ignored, if relatedToAll is also used.
relatedToAll[Int]Narrows the query results to elements that relate to all of the provided element IDs. Using this argument will cause relatedTo argument to be ignored.
ref[String]Narrows the query results based on a reference string.
fixedOrderBooleanCauses the query results to be returned in the order specified by the id argument.
inReverseBooleanCauses the query results to be returned in reverse order.
dateCreated[String]Narrows the query results based on the elements’ creation dates.
dateUpdated[String]Narrows the query results based on the elements’ last-updated dates.
offsetIntSets the offset for paginated results.
limitIntSets the limit for paginated results.
orderByStringSets the field the returned elements should be ordered by.
handle[String]Narrows the query results based on the form’s handle.

The FormInterface interface#

This is the interface implemented by all forms.

FieldTypeDescription
idIDThe id of the entity.
uidStringThe uid of the entity.
titleStringThe element’s title.
enabledBooleanWhether the element is enabled or not.
archivedBooleanWhether the element is archived or not.
searchScoreStringThe element’s search score, if the search parameter was used when querying for the element.
trashedBooleanWhether the element has been soft-deleted or not.
dateCreatedDateTimeThe date the element was created.
dateUpdatedDateTimeThe date the element was last updated.
handleStringThe form’s handle.
pages[PageInterface]The form’s pages.
rows[RowInterface]The form’s rows.
formFields[FieldInterface]The form’s fields.
settings[FormSettingsInterface]The form’s settings.
configJsonStringThe form’s config as JSON.
templateHtmlStringThe form’s rendered HTML.
csrfToken[CsrfTokenInterface]A CSRF token (name and value).
captchas[CaptchaValueInterface]A list of captcha values (name and value) to assist with spam protection.
submissionMutationNameStringThe form’s GQL mutation name for submissions to use.
submissionEndpointStringThe form’s endpoint for sending submissions to, if using POST requests.

The formFields query#

This query is used to query for Field objects on a form.

ArgumentTypeDescription
includeDisabledBooleanExpands the query results to include fields that have a visibility of "disabled". These are omitted by default.

The templateHtml query#

You can also add query arguments to templateHtml to narrow your results.

ArgumentTypeDescription
optionsStringThe form template HTML will be rendered with these JSON serialized options.
populateFormValuesStringThe form field values will be populated with these JSON serialized options.

The FormSettingsInterface interface#

This is the interface implemented by all forms.

FieldTypeDescription
displayFormTitleBooleanWhether to show the form’s title.
displayCurrentPageTitleBooleanWhether to show the form’s current page title.
displayPageTabsBooleanWhether to show the form’s page tabs.
displayPageProgressBooleanWhether to show the form’s page progress.
scrollToTopBooleanWhether to the form should scroll to the top of the page when submitted.
progressPositionStringThe form’s progress bar position. Either start or end.
defaultLabelPositionString!The form’s default label position for fields. This will be a verbb\formie\positions class name.
defaultInstructionsPositionString!The form’s default instructions position for fields. This will be a verbb\formie\positions class name.
submitMethodString!The form’s submit method. Either page-reload or ajax.
submitActionString!The form’s submit action. Either message, entry, url, reload.
submitActionTabString!The form’s submit redirect option (if in new tab or same tab). Either same-tab or new-tab.
submitActionFormHideBooleanWhether to hide the form’s success message.
submitActionMessageHtmlStringThe form’s submit success message.
submitActionMessageTimeoutIntegerThe form’s submit success message timeout in seconds.
submitActionMessagePositionStringThe form’s submit message position. Either top-form or bottom-form.
loadingIndicatorString!The type of loading indicator to use. Either spinner or text.
loadingIndicatorTextString!The form’s loading indicator text.
validationOnSubmitBooleanWhether to validate the form’s on submit.
validationOnFocusBooleanWhether to validate the form’s on focus.
errorMessageHtmlStringThe form’s submit error message.
errorMessagePositionStringThe form’s error message position. Either null, top-form or bottom-form.
redirectUrlString!The form’s submit action redirect URL, resolved depending on submitAction being entry or url.
redirectEntryEntryInterface!The form’s submit action entry (for redirection), if submitAction is entry.
integrations[FormIntegrationsInterface]The form’s enabled integrations.

The FormIntegrationsInterface interface#

This is the interface implemented by all form integrations.

FieldTypeDescription
nameStringThe integration’s name.
handleStringThe integration’s handle.
enabledBooleanWhether the integration is enabled.
settingsStringThe integration’s settings as a JSON string.

The PageInterface interface#

This is the interface implemented by all pages.

FieldTypeDescription
idIDThe id of the entity.
uidStringThe uid of the entity.
dateCreatedDateTimeThe date the element was created.
dateUpdatedDateTimeThe date the element was last updated.
nameStringThe name of the page.
rows[RowInterface]The pages’s rows.
pageFields[FieldInterface]The pages’s fields.
settings[PageSettingsInterface]The pages’s settings, including buttons.

The pageFields query#

This query is used to query for Field objects on a page.

ArgumentTypeDescription
includeDisabledBooleanExpands the query results to include fields that have a visibility of "disabled". These are omitted by default.

The PageSettingsInterface interface#

This is the interface implemented by all pages.

FieldTypeDescription
submitButtonLabelString!The page’s submit button label.
backButtonLabelString!The page’s back button label.
showBackButtonBooleanWhether to show the page’s back button.
buttonsPositionStringThe page’s button (back and submit) positions.
cssClassesString!The page’s button (back and submit) CSS classes.
containerAttributes| [FieldAttribute]!`The page’s button (back and submit) container attributes.
inputAttributes| [FieldAttribute]!`The page’s button (back and submit) input attributes.
enablePageConditionsBooleanWhether the page has conditions enabled.
pageConditionsStringThe page’s conditions as a JSON string.
enableNextButtonConditionsBooleanWhether the page’s next button has conditions enabled, for multi-page forms.
nextButtonConditionsStringThe page’s conditions for whether to show the next button, for multi-page forms as a JSON string.

The RowInterface interface#

This is the interface implemented by all rows.

FieldTypeDescription
idIDThe id of the entity.
uidStringThe uid of the entity.
rowFields[FieldInterface]The row’s fields.

The rowFields query#

This query is used to query for Field objects on a row.

ArgumentTypeDescription
includeDisabledBooleanExpands the query results to include fields that have a visibility of "disabled". These are omitted by default.

The FieldInterface interface#

This is the interface implemented by all fields. Note that as settings are specific to fields, you'll need to use Inline Fragments (opens new window).

FieldTypeDescription
idIDThe id of the entity.
uidStringThe uid of the entity.
nameStringThe field’s name.
handleStringThe field’s handle.
instructionsStringThe field’s instructions.
requiredBooleanWhether the field is required or not.
typeStringThe field’s full class type.
displayNameStringThe field’s display name (last portion of the class).
typeNameStringThe field’s full GQL type.
inputTypeNameStringThe field’s full GQL input type. Useful for mutations.
matchFieldString!The field handle for another field that this value should match exactly.
placeholderString!The field’s placeholder.
defaultValueStringThe field’s default value as a string. Some fields have different fields for their default value.
prePopulateString!The field’s pre-populated value extracted from the query string.
errorMessageString!The field’s error message.
labelPositionString!The field’s label position. This will be a verbb\formie\positions class name.
instructionsPositionString!The field’s instructions position. This will be a verbb\formie\positions class name.
cssClassesString!The field’s CSS classes.
containerAttributes[FieldAttribute]The field’s container attributes.
inputAttributes[FieldAttribute]The field’s input attributes.
includeInEmailBooleanWhether the field should be included in email content.
enableConditionsBooleanWhether the field has conditions enabled.
conditionsString!The field’s conditions as a JSON string.
enableContentEncryptionBooleanWhether the field has content encryption enabled.
visibilityString!The field’s visibility.

Once using the necessary Inline Fragments (opens new window) for each field type, you'll have access to the same variables as described on the Field docs.

Address Fields#

FieldTypeDescription
autocompleteLabelString!The label for the Autocomplete sub-field.
autocompletePlaceholderString!The placeholder for the Autocomplete sub-field.
autocompleteDefaultValueString!The default value for the Autocomplete sub-field.
autocompleteRequiredBooleanWhether the Autocomplete sub-field should be required.
autocompleteErrorMessageString!The error message for the Autocomplete sub-field.
autocompleteCollapsedBooleanWhether the Autocomplete sub-field is collapsed in the control panel.
autocompleteEnabledBooleanWhether the Autocomplete sub-field is enabled in the control panel.
autocompleteCurrentLocationBooleanWhether the Autocomplete sub-field should show a "Show location" link.
autocompletePrePopulateString!The field’s pre-populated value extracted from the query string.
autocompleteIntegrationString!The handle of the Address Provider integration, if set.
address1LabelString!The label for the Address 1 sub-field.
address1PlaceholderString!The placeholder for the Address 1 sub-field.
address1DefaultValueString!The default value for the Address 1 sub-field.
address1RequiredBooleanWhether the Address 1 sub-field should be required.
address1ErrorMessageString!The error message for the Address 1 sub-field.
address1CollapsedBooleanWhether the Address 1 sub-field is collapsed in the control panel.
address1EnabledBooleanWhether the Address 1 sub-field is enabled in the control panel.
address1HiddenBooleanWhether the Address 1 sub-field is hidden.
address2LabelString!The label for the Address 2 sub-field.
address2PlaceholderString!The placeholder for the Address 2 sub-field.
address2DefaultValueString!The default value for the Address 2 sub-field.
address2RequiredBooleanWhether the Address 2 sub-field should be required.
address2ErrorMessageString!The error message for the Address 2 sub-field.
address2CollapsedBooleanWhether the Address 2 sub-field is collapsed in the control panel.
address2EnabledBooleanWhether the Address 2 sub-field is enabled in the control panel.
address2HiddenBooleanWhether the Address 2 sub-field is hidden.
address3LabelString!The label for the Address 3 sub-field.
address3PlaceholderString!The placeholder for the Address 3 sub-field.
address3DefaultValueString!The default value for the Address 3 sub-field.
address3RequiredBooleanWhether the Address 3 sub-field should be required.
address3ErrorMessageString!The error message for the Address 3 sub-field.
address3CollapsedBooleanWhether the Address 3 sub-field is collapsed in the control panel.
address3EnabledBooleanWhether the Address 3 sub-field is enabled in the control panel.
address3HiddenBooleanWhether the Address 3 sub-field is hidden.
cityLabelString!The label for the City sub-field.
cityPlaceholderString!The placeholder for the City sub-field.
cityDefaultValueString!The default value for the City sub-field.
cityRequiredBooleanWhether the City sub-field should be required.
cityErrorMessageString!The error message for the City sub-field.
cityCollapsedBooleanWhether the City sub-field is collapsed in the control panel.
cityEnabledBooleanWhether the City sub-field is enabled in the control panel.
cityHiddenBooleanWhether the City sub-field is hidden.
stateLabelString!The label for the State sub-field.
statePlaceholderString!The placeholder for the State sub-field.
stateDefaultValueString!The default value for the State sub-field.
stateRequiredBooleanWhether the State sub-field should be required.
stateErrorMessageString!The error message for the State sub-field.
stateCollapsedBooleanWhether the State sub-field is collapsed in the control panel.
stateEnabledBooleanWhether the State sub-field is enabled in the control panel.
stateHiddenBooleanWhether the State sub-field is hidden.
zipLabelString!The label for the Zip sub-field.
zipPlaceholderString!The placeholder for the Zip sub-field.
zipDefaultValueString!The default value for the Zip sub-field.
zipRequiredBooleanWhether the Zip sub-field should be required.
zipErrorMessageString!The error message for the Zip sub-field.
zipCollapsedBooleanWhether the Zip sub-field is collapsed in the control panel.
zipEnabledBooleanWhether the Zip sub-field is enabled in the control panel.
zipHiddenBooleanWhether the Zip sub-field is hidden.
countryLabelString!The label for the Country sub-field.
countryPlaceholderString!The placeholder for the Country sub-field.
countryDefaultValueString!The default value for the Country sub-field.
countryRequiredBooleanWhether the Country sub-field should be required.
countryErrorMessageString!The error message for the Country sub-field.
countryCollapsedBooleanWhether the Country sub-field is collapsed in the control panel.
countryEnabledBooleanWhether the Country sub-field is enabled in the control panel.
countryHiddenBooleanWhether the Country sub-field is hidden.
countryOptions[FieldAttribute]An array of options available to pick a country from.

Agree#

FieldTypeDescription
descriptionString!The description for the field. This will be shown next to the checkbox.
descriptionHtmlStringThe HTML description for the field.
checkedValue String!The value of this field when it is checked.
uncheckedValueString!The value of this field when it is unchecked.
defaultStateBooleanWhether the default state should be checked or unchecked.

Calculations#

FieldTypeDescription
formulaString!A JSON string including the parsed formula and variables for any fields used in the formula.

Categories#

FieldTypeDescription
placeholderString!The option shown initially, when no option is selected.
sourceString!Which source do you want to select categories from?
branchLimitString!Limit the number of selectable category branches.
categoriesCategoryQueryThe category query for available categories.

Checkboxes#

FieldTypeDescription
options[FieldOption]Define the available options for users to select from.
layoutStringSelect which layout to use for these fields.
toggleCheckboxString!Whether to add an additional checkbox to toggle all checkboxes in this field by. Either null, top, bottom.
toggleCheckboxLabelString!The label for the toggle checkbox field.

Date/Time#

FieldTypeDescription
defaultDateDateTimeThe default date to be used for the field.
displayTypeStringThe display layout for this field. Either calendar, dropdowns or inputs.
dateFormatStringThe chosen format for the date.
timeFormatStringThe chosen format for the time.
includeDateBooleanWhether this field should include the date.
includeTimeBooleanWhether this field should include the time.
timeLabelString!The label for the time sub-field.
dayLabelString!The label for the day sub-field.
dayPlaceholderString!The placeholder for the day sub-field.
monthLabelString!The label for the month sub-field.
monthPlaceholderString!The placeholder for the month sub-field.
yearLabelString!The label for the year sub-field.
yearPlaceholderString!The placeholder for the year sub-field.
hourLabelString!The label for the hour sub-field.
hourPlaceholderString!The placeholder for the hour sub-field.
minuteLabelString!The label for the minute sub-field.
minutePlaceholderString!The placeholder for the minute sub-field.
secondLabelString!The label for the second sub-field.
secondPlaceholderString!The placeholder for the second sub-field.
ampmLabelString!The label for the AM/PM sub-field.
ampmPlaceholderString!The placeholder for the AM/PM sub-field.
useDatePickerBooleanWhether this field should use the Flatpickr datepicker.
datePickerOptionsBooleanA collection of options for the Flatpickr datepicker.
minDateDateTimeThe minimum allowed date.
maxDateDateTimeThe maximum allowed date.
FieldTypeDescription
multipleBooleanWhether this field should allow multiple options to be selected.
options[FieldOption]Define the available options for users to select from.
defaultValueStringEntering a default value will place the value in the field when it loads.

Email Address#

FieldTypeDescription
placeholderStringThe text that will be shown if the field doesn’t have a value.
defaultValueStringEntering a default value will place the value in the field when it loads.
validateDomainBooleanWhether to validate the domain when the value is saved.
blockedDomains[String]!A list of domains to block values.
uniqueValueBooleanWhether to the value of this field should be unique across all submissions for the form.

Entries#

FieldTypeDescription
placeholderStringThe option shown initially, when no option is selected.
sourcesStringWhich sources do you want to select entries from?
limitStringLimit the number of selectable entries.
entriesEntryQueryThe entry query for available entries.

File Upload#

FieldTypeDescription
uploadLocationSourceStringThe volume for files to be uploaded into.
uploadLocationSubpathStringThe sub-path for the files to be uploaded into.
limitFilesStringLimit the number of files a user can upload.
sizeLimitStringLimit the size of the files a user can upload.
allowedKindsStringA collection of allowed mime-types the user can upload.

Group#

See nested fields for how to query the inner fields.

Heading#

FieldTypeDescription
headingSizeString!Choose the size for the heading.

Hidden#

FieldTypeDescription
defaultOptionString!The selected option for the preset default value chosen.
defaultValueString!Entering a default value will place the value in the field when it loads. This will be dependent on the value chosen for the defaultOption.
queryParameterString!If query string is selected for the defaultOption, this will contain the query string parameter to look up.
cookieNameString!If cookie is selected for the defaultOption, this will contain the cookie name to look up.

Html#

FieldTypeDescription
htmlContentString!Enter HTML content to be rendered for this field.

Multi-Line Text#

FieldTypeDescription
placeholderStringThe text that will be shown if the field doesn’t have a value.
defaultValueStringEntering a default value will place the value in the field when it loads.
limitBooleanWhether the field should limit content.
limitTypeString!The field’s limiting type. Either characters or words.
limitAmountInt!The field’s number of characters/words to limit, based on limitType.
useRichTextBooleanWhether the front-end of the field should use a Rich Text editor. This is powered by Pell (opens new window).
richTextButtons[String]!An array of available buttons the Rich Text field should use. Consult the Pell (opens new window) docs for these options.

Name#

FieldTypeDescription
useMultipleFieldsBooleanWhether this field should use multiple fields for users to enter their details.
prefixLabelStringThe label for the Prefix sub-field.
prefixPlaceholderStringThe placeholder for the Prefix sub-field.
prefixDefaultValueStringThe default value for the Prefix sub-field.
prefixRequiredBooleanWhether the Prefix sub-field should be required.
prefixErrorMessageStringThe error message for the Prefix sub-field.
prefixCollapsedBooleanWhether the Prefix sub-field is collapsed in the control panel.
prefixEnabledBooleanWhether the Prefix sub-field is enabled in the control panel.
prefixOptions[FieldAttribute]An array of options available to pick a prefix from.
firstNameLabelStringThe label for the First Name sub-field.
firstNamePlaceholderStringThe placeholder for the First Name sub-field.
firstNameDefaultValueStringThe default value for the First Name sub-field.
firstNameRequiredBooleanWhether the First Name sub-field should be required.
firstNameErrorMessageStringThe error message for the First Name sub-field.
firstNameCollapsedBooleanWhether the First Name sub-field is collapsed in the control panel.
firstNameEnabledBooleanWhether the First Name sub-field is enabled in the control panel.
middleNameLabelStringThe label for the Middle Name sub-field.
middleNamePlaceholderStringThe placeholder for the Middle Name sub-field.
middleNameDefaultValueStringThe default value for the Middle Name sub-field.
middleNameRequiredBooleanWhether the Middle Name sub-field should be required.
middleNameErrorMessageStringThe error message for the Middle Name sub-field.
middleNameCollapsedBooleanWhether the Middle Name sub-field is collapsed in the control panel.
middleNameEnabledBooleanWhether the Middle Name sub-field is enabled in the control panel.
lastNameLabelStringThe label for the Last Name sub-field.
lastNamePlaceholderStringThe placeholder for the Last Name sub-field.
lastNameDefaultValueStringThe default value for the Last Name sub-field.
lastNameRequiredBooleanWhether the Last Name sub-field should be required.
lastNameErrorMessageStringThe error message for the Last Name sub-field.
lastNameCollapsedBooleanWhether the Last Name sub-field is collapsed in the control panel.
lastNameEnabledBooleanWhether the Last Name sub-field is enabled in the control panel.

Number#

FieldTypeDescription
placeholderStringThe text that will be shown if the field doesn’t have a value.
defaultValueStringEntering a default value will place the value in the field when it loads.
limitBooleanWhether to limit the numbers for this field.
minFloatThe minimum number that can be entered for this field.
maxFloatThe maximum number that can be entered for this field.
decimalsInt!Set the number of decimal points to format the field value.

Payment#

FieldTypeDescription
paymentIntegrationString!The handle of the Payment Integration chosen.
paymentIntegrationTypeString!The class of the Payment Integration chosen.
providerSettingsString!A JSON string of settings for the payment provider to use.

Phone#

FieldTypeDescription
showCountryCodeStringWhether to show an additional dropdown for selecting the country code.
countryLabelStringThe label for the Country sub-field.
countryPlaceholderStringThe placeholder for the Country sub-field.
countryDefaultValueStringThe default value for the Country sub-field.
countryCollapsedBooleanWhether the Country sub-field is collapsed in the control panel.
countryEnabledBooleanWhether the Country sub-field is enabled in the control panel.
countryOptions[FieldAttribute]An array of options available to pick a country from.
numberLabelStringThe label for the Number sub-field.
numberPlaceholderStringThe placeholder for the Number sub-field.
numberDefaultValueString!The default value for the Number sub-field.
numberCollapsedBooleanWhether the Number sub-field is collapsed in the control panel.

Products#

FieldTypeDescription
placeholderStringThe option shown initially, when no option is selected.
sourcesStringWhich sources do you want to select products from?
limitBooleanLimit the number of selectable products.
productsProductQueryThe product query for available products.

Radio#

FieldTypeDescription
options[FieldOption]Define the available options for users to select from.
layoutStringSelect which layout to use for these fields. Either vertical or horizontal,

Recipients#

FieldTypeDescription
displayTypeStringWhat sort of field to show on the front-end for users. Either hidden, dropdown, checkboxes or radio.
options[FieldOption]Define the available options for users to select from.

Repeater#

See nested fields for how to query the inner fields.

FieldTypeDescription
addLabelString!The label for the button that adds another instance.
minRowsInt!The minimum required number of instances of this repeater's fields that must be completed.
maxRowsInt!The maximum required number of instances of this repeater's fields that must be completed.

Section#

FieldTypeDescription
borderString!Add a border to this section.
borderWidthInt!Set the border width (in pixels).
borderColorString!Set the border color.

Single-Line Text#

FieldTypeDescription
placeholderStringThe text that will be shown if the field doesn’t have a value.
defaultValueStringEntering a default value will place the value in the field when it loads.
limitBooleanWhether to limit the content of this field.
limitTypeString!The field’s limiting type. Either characters or words.
limitAmountInt!The field’s number of characters/words to limit, based on limitType.

Table#

FieldTypeDescription
columns[TableColumn]!Define the columns your table should have.
defaultsString!Define the default values for the field as a JSON string.
addRowLabelStringThe label for the button that adds another row.
staticBooleanWhether this field should disallow adding more rows, showing only the default rows.
minRowsInt!The minimum required number of rows in this table that must be completed.
maxRowsInt!The maximum required number of rows in this table that must be completed.

Tags#

FieldTypeDescription
placeholderStringThe option shown initially, when no option is selected.
sourceStringWhich source do you want to select tags from?
tagsTagQueryThe tag query for available tags.

Users#

FieldTypeDescription
placeholderStringThe option shown initially, when no option is selected.
sourcesStringWhich sources do you want to select users from?
limitStringLimit the number of selectable users.
usersUserQueryThe user query for available users.

Variants#

FieldTypeDescription
placeholderStringThe option shown initially, when no option is selected.
source StringWhich source do you want to select variants from?
limitStringLimit the number of selectable variants.
variantsVariantQueryThe variant query for available variants.

Nested Fields#

For nested fields like Group and Repeater, you have access to nestedRows and fields.

{
    formieForm (handle: "contactForm") {
        title
        handle
        
        formFields {
            name

            ... on Field_Group {
                nestedRows {
                    fields {
                        name
                    }
                }
            }
        }
    }
}

The FieldAttribute interface#

This interface defines a key-value stored value, where you want the label and value.

FieldTypeDescription
labelStringThe label of the attribute.
valueStringThe value of the attribute.

The FieldOption interface#

For option-based fields, a FieldOption represents a single option row.

FieldTypeDescription
labelStringThe label of the option.
valueStringThe value of the option.
isOptgroupBooleanWhether this option has been marked as an optgroup.
isDefaultBooleanWhether this option has been marked as a default.

The TableColumn interface#

This interface defines the columns for a Table field.

FieldTypeDescription
headingStringThe column heading.
handleStringThe column handle.
widthStringThe column width.
typeStringThe column type.

The CsrfTokenInterface interface#

This is the interface to allow easy retrieval of a CSRF token and value.

FieldTypeDescription
nameStringThe CSRF name.
valueStringThe CSRF token.

The CaptchaValueInterface interface#

This is the interface to fetch enabled captchas for the form.

FieldTypeDescription
handleStringThe captcha name.
nameStringThe captcha name.
valueStringThe captcha value.

Submissions#

Example#

{
    formieSubmissions (form: "contactForm") {
        title

        ... on contactForm_Submission {
            yourName
            emailAddress
            message
        }
    }
}
{
    "data": {
        "formieSubmissions": [
            {
                "title": "2020-07-24 22:01:59",
                "yourName": "Peter Sherman",
                "emailAddress": "psherman@wallaby.com",
                "message": "Just wanted to say hi!"
            }
        ]
    }
}

The formieSubmissions query#

This query is used to query for Submission objects. You can also use the singular formieSubmission to fetch a single submission.

ArgumentTypeDescription
id[QueryArgument]Narrows the query results based on the elements’ IDs.
uid[String]Narrows the query results based on the elements’ UIDs.
archivedBooleanNarrows the query results to only elements that have been archived.
trashedBooleanNarrows the query results to only elements that have been soft-deleted.
uniqueBooleanDetermines whether only elements with unique IDs should be returned by the query.
title[String]Narrows the query results based on the elements’ titles.
searchStringNarrows the query results to only elements that match a search query.
relatedTo[Int]Narrows the query results to elements that relate to any of the provided element IDs. This argument is ignored, if relatedToAll is also used.
relatedToAll[Int]Narrows the query results to elements that relate to all of the provided element IDs. Using this argument will cause relatedTo argument to be ignored.
ref[String]Narrows the query results based on a reference string.
fixedOrderBooleanCauses the query results to be returned in the order specified by the id argument.
inReverseBooleanCauses the query results to be returned in reverse order.
dateCreated[String]Narrows the query results based on the elements’ creation dates.
dateUpdated[String]Narrows the query results based on the elements’ last-updated dates.
offsetIntSets the offset for paginated results.
limitIntSets the limit for paginated results.
orderByStringSets the field the returned elements should be ordered by.
form[String]Narrows the query results based on the form’s handle.

Nested Fields#

An example for querying Repeater and Group field content.

{
    formieSubmissions (handle: "contactForm") {
        title
        
        ... on contactForm_Submission {
            groupFieldHandle {
                myFieldHandle
            }

            repeaterFieldHandle {
                rows {
                    myFieldHandle
                }
            }
        }
    }
}

Mutations#

Mutations in GraphQL provide a way of modifying data. The actual mutations will vary depending on the schema. There are some common mutations per GraphQL object type as well as type-specific mutations.

Be sure to read the GraphQL docs (opens new window).

Submissions#

Saving a submission#

To create or update a submission use the form-specific mutation, which will have the name in the form of save_<formHandle>_Submission.

ArgumentTypeDescription
idIDSet the element’s ID.
uidStringSet the element’s UID.
enabledBooleanWhether the element should be enabled.
titleStringSet the element’s title.
statusStringSet the element’s status as its handle.
statusIdIntSet the element’s statusId.
isIncompleteBooleanSet the element’s incomplete state.
...More arguments depending on the field layout for the form

The below shows an example request to create a new submission. For this form, we have a single-line text field with the handle yourName. In our query variables, we pass the value(s) we want to use in the query.

// Query
mutation saveSubmission($yourName:String) {
    save_contactForm_Submission(yourName: $yourName) {
        title
        yourName
    }
}

// Query Variables
{
    "yourName": "Peter Sherman"
}

With the resulting output:

{
    "data": {
        "save_contactForm_Submission": {
            "title": "2020-08-18 10:29:06",
            "yourName": "Peter Sherman"
        }
    }
}

Complex Fields#

Some fields, such as Name and Address fields are much more than primitive values. Instead, their content needs to be provided as an object. The Name field is an exception, as it can be set to have multiple fields, or a single field.

For example, you can populate a name and address field using the below:

// Query
mutation saveSubmission($yourName:contactForm_yourName_FormieNameInput $yourAddress:contactForm_yourAddress_FormieAddressInput) {
    save_contactForm_Submission(yourName: $yourName, yourAddress: $yourAddress) {
        yourName
        yourAddress
    }
}

// Query Variables
{
    "yourName": {
        "firstName": "Peter",
        "lastName": "Sherman"
    },
    "yourAddress": {
        "address1": "42 Wallaby Way",
        "city": "Sydney",
        "zip": "2000",
        "state": "NSW",
        "country": "Australia"
    }
}

You'll notice the contactForm_yourName_FormieNameInput type being used. This follows the structure of {formHandle}_{fieldHandle}_FormieNameInput. There are also a number of other input types to consider.

Address Field#

// Query
mutation saveSubmission($yourAddress:contactForm_yourAddress_FormieAddressInput) {
    save_contactForm_Submission(yourAddress: $yourAddress) {
        yourAddress
    }
}

// Query Variables
{
    "yourAddress": {
        "address1": "42 Wallaby Way",
        "city": "Sydney",
        "zip": "2000",
        "state": "NSW",
        "country": "Australia"
    }
}

File Upload Field#

When uploading a file, you must provide an array of upload data with a base64 encoded data, so that Formie can create the asset element. Provide this as fileData, and you can also supply an optional filename variable to name the asset correctly. If you do not supply this, a filename will be generated for you.

// Query
mutation saveSubmission($fileUploadField:[FileUploadInput]) {
    save_contactForm_Submission(fileUploadField: $fileUploadField) {
        title
    }
}

// Query Variables
{
    "fileUploadField": [
        {
            "fileData": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQUA...",
            "filename": "testing.png"
        },
        {
            "fileData": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQUA..."
        }
    ]
}

If you have already uploaded your asset through other means, you can provide an assetId in the same fashion.

// Query
mutation saveSubmission($fileUploadField:[FileUploadInput]) {
    save_contactForm_Submission(fileUploadField: $fileUploadField) {
        title
    }
}

// Query Variables
{
    "fileUploadField": [
        {
            "assetId": 1234
        },
        {
            "assetId": 4562
        }
    ]
}

Group Field#

// Query
mutation saveSubmission($groupField:contactForm_groupField_FormieGroupInput) {
    save_contactForm_Submission(groupField: $groupField) {
        groupField {
            firstValue: firstValue
            secondValue: secondValue
        }
    }
}

// Query Variables
{
    "groupField": {
        "firstValue": "This content",
        "secondValue": "is for groups"
    }
}

Repeater Field#

// Query
mutation saveSubmission($repeaterField:contactForm_repeaterField_FormieRepeaterInput) {
    save_contactForm_Submission(repeaterField: $repeaterField) {
        repeaterField {
            rows: {
                field1: field1
                field2: field2
            }
        }
    }
}

// Query Variables
{
    "repeaterField": {
        "rows": [
            {
                "field1": "First Block - Field 1",
                "field2": "First Block - Field 2"
            },
            {
                "field1": "Second Block - Field 1",
                "field2": "Second Block - Field 2"
            }
        ]
    }
}

Deleting a submission#

To delete a submission use the deleteSubmission mutation, which requires the id of the submission that must be deleted. It returns a boolean value as the result to indicate whether the operation was successful.

// Query to delete a submission with ID of `1110` for a site with an ID of `2`.
mutation deleteSubmission {
    deleteSubmission(id:1110 siteId:2)
}

With the resulting output:

{
    "data": {
        "deleteSubmission": true
    }
}

Validation#

If a mutation triggers a validation error, you'll get a response back, similar to the below. Here, the example shows the user didn't provide an email address, for the emailAddress field, despite it being required. The message will always be a JSON-encoded response of errors.

{
    "errors": [
        {
            "message": "{\"emailAddress\":[\"Email Address cannot be blank.\"]}",
            "extensions": {
                "category": "graphql"
            }
        }
    ],
    "data": {
        "save_contactForm_Submission": null
    }
}

Captchas#

You'll likely want to implement some form of captcha on the front-end for your headless forms. We would recommend either reCAPTCHA (opens new window) or hCaptcha (opens new window), as other captchas require a bit more work. Refer to our Headless Demo (opens new window) for more information on the specifics of this, primarily to deal with CORS, and cross-site cookies.

You can add the following to your GQL form query to fetch tokens generated server-side.

{
    formieForm (handle: "contactForm") {
        ...

        captchas {
            handle
            name
            value
        }
    }
}

Here, you'll need 3 vital bits of information, which is the handle of the Captcha integration, the name of the session variable used to compare the tokens between client and server, and the value of the token.

To authenticate your enabled Captchas correctly, you'll need to include these in your mutation, sent to the server.

// Query
mutation saveSubmission($yourName:contactForm_yourName_FormieNameInput $javascriptCaptcha: FormieCaptchaInput) {
    save_contactForm_Submission(yourName: $yourName, javascriptCaptcha: $javascriptCaptcha) {
        title
    }
}

// Query Variables
{
    "yourName": {
        "firstName": "Peter",
        "lastName": "Sherman"
    },
    "javascriptCaptcha": {
        "name": "__JSCHK_8403842",
        "value": "1234"
    }
}

Here, we've included an additional parameter that includes the handle, name and value of the captcha in our mutation.

For an example with reCAPTCHA, refer to our Headless Demo docs (opens new window).

Previous ← JavaScript API Next Console Commands →

Get started with Formie

Available for Craft 4. Get it from the plugin store.