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

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.

Get started with Formie

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