GraphQL

Formie supports accessing Form and Submission objects via GraphQL. Be sure to read about Craft's GraphQL support.

Forms #

Query payload #

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

        settings {
            errorMessageHtml
        }
        
        pages {
            name

            rows {
                fields {
                    name
                    handle
                    type
                    displayName
                    columnWidth

                    ... on Field_Name {
                        firstNameLabel
                        firstNameRequired
                        lastNameLabel
                        lastNameRequired
                    }

                    ... on Field_Email {
                        placeholder
                    }
                }
            }
        }
    }
}

The response #

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

The forms query #

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

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.
pages[PageInterface]The form’s pages.
rows[RowInterface]The form’s rows.
fields[FieldInterface]The form’s fields.
settings[FormSettingsInterface]The form’s settings.

The FormSettingsInterface interface #

This is the interface implemented by all forms.

FieldTypeDescription
displayFormTitleBooleanWhether to show the form’s title.
displayPageTabsBooleanWhether to show the form’s page tabs.
displayCurrentPageTitleBooleanWhether to show the form’s current page title.
displayPageProgressBooleanWhether to show the form’s page progress.
submitMethodStringThe form’s submit method.
submitActionStringThe form’s submit action.
submitActionTabStringThe form’s submit redirect option (if in new tab or same tab).
submitActionUrlStringThe form’s submit action URL.
submitActionFormHideBooleanWhether to hide the form’s success message.
submitActionMessageHtmlStringThe form’s submit success message.
submitActionMessageTimeoutIntegerThe form’s submit success message timeout.
errorMessageHtmlStringThe form’s submit error message.
loadingIndicatorBooleanWhether to show the form’s loading indicator.
loadingIndicatorTextStringThe form’s loading indicator text.
validationOnSubmitBooleanWhether to validate the form’s on submit.
validationOnFocusBooleanWhether to validate the form’s on focus.
defaultLabelPositionStringThe form’s default label position for fields.
defaultInstructionsPositionStringThe form’s default instructions position for fields.
progressPositionStringThe form’s progress bar position.

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.
fields[FieldInterface]The pages’s fields.
settings[PageSettingsInterface]The pages’s settings

The PageSettingsInterface interface #

This is the interface implemented by all pages.

FieldTypeDescription
submitButtonLabelStringThe page’s submit button label.
backButtonLabelStringThe page’s back button label.
showBackButtonBooleanWhether to show the page’s back button.
buttonsPositionStringThe page’s button positions.

The RowInterface interface #

This is the interface implemented by all rows.

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

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.

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.
columnWidthIntThe field’s column width.
typeStringThe field’s full class type.
displayNameStringThe field’s display name (last portion of the class).

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

Nested Fields

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

{
    form (handle: "contactForm") {
        title
        handle
        
        fields {
            name

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

Submissions #

Query payload #

{
    submissions (form: "contactForm") {
        title

        ... on contactForm_Submission {
            yourName
            emailAddress
            message
        }
    }
}

The response #

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

The submissions query #

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

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.

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.

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.
...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.

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`.
mutation deleteSubmission {
    deleteSubmission(id:1110)
}

With the resulting output:

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

Get started with Formie

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