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

                    ... 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",
                                    "firstNameLabel": "First Name",
                                    "firstNameRequired": true,
                                    "lastNameLabel": "Last Name",
                                    "lastNameRequired": true
                                }
                            ]
                        },
                        {
                            "fields": [
                                {
                                    "name": "Email Address",
                                    "handle": "emailAddress",
                                    "type": "verbb\\formie\\fields\\formfields\\Email",
                                    "displayName": "Email",
                                    "placeholder": "eg. psherman@wallaby.com"
                                }
                            ]
                        },
                        {
                            "fields": [
                                {
                                    "name": "Message",
                                    "handle": "message",
                                    "type": "verbb\\formie\\fields\\formfields\\MultiLineText",
                                    "displayName": "MultiLineText"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    }
}

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.

The FormInterface interface #

This is the interface implemented by all forms.

The FormSettingsInterface interface #

This is the interface implemented by all forms.

The FormIntegrationsInterface interface #

This is the interface implemented by all form integrations.

The PageInterface interface #

This is the interface implemented by all pages.

The PageSettingsInterface interface #

This is the interface implemented by all pages.

The RowInterface interface #

This is the interface implemented by all rows.

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.

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

Address Fields #

Agree #

Categories #

Checkboxes #

Date/Time #

Dropdown #

Email Address #

Entries #

File Upload #

Heading #

Hidden #

Html #

Multi-Line Text #

Name #

Number #

Phone #

Products #

Radio #

Repeater #

Recipients #

Section #

Single-Line Text #

Table #

Tags #

Users #

Variants #

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

The CsrfTokenInterface interface #

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

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.

Nested Fields #

An example for querying Repeater and Group field content.

{
    submissions (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.

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.

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"
    }
}

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