Freeform for Craft

5.x ✓ Latest

• 5.x✓ Latest
• 4.x
• 3.xRetired
• 2.xRetired
• 1.xRetired

Plugin Store

Headless

# GraphQL

LitePro

Freeform supports querying form layouts and form submission mutations via GraphQL. This guide assumes you have some GraphQL experience. To learn more about GraphQL and Craft, please check out the Fetch content with GraphQL guide and Craft's GraphQL API.

# Demos

Have a look at our headless demos to get a feel for what's possible with GraphQL:

• VueJS + GraphQL implementations
• ReactJS + GraphQL implementations
• NextJS + GraphQL implementations

# Queries

# Querying Freeform data

Freeform has a root freeform query, which contains all the possible queries nested inside it to avoid conflicts with other plugins.

# Querying multiple Forms

To query all or some forms, you have to use the forms query:

query {
  freeform {
    forms {
      name
      handle
      pages {
        label
        rows {
          fields {
            id
            type
            label
            handle
            required
          }
        }
      }
    }
  }
}

Example response data:

{
  "data": {
    "freeform": {
      "forms": [
        {
          "name": "My Form",
          "handle": "myForm",
          "pages": [
            {
              "label": "First Page",
              "rows": [
                {
                  "fields": [
                    {
                      "type": "text",
                      "label": "First Name",
                      "handle": "firstName",
                      "required": false
                    },
                    {
                      "type": "text",
                      "label": "Last Name",
                      "handle": "lastName",
                      "required": true
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

# Querying a single Form

You can query a single form directly by using the form query:

query {
  freeform {
    form (handle: "my-form") {
      name
      handle
      pages {
        # ...
      }
    }
  }
}

Example response data:

{
  "data": {
    "freeform": {
      "form": {
        "name": "My Form",
        "handle": "myForm",
        "pages": [
          {
            "label": "First Page",
            "rows": [
              {
                "fields": [
                  {
                    "type": "text",
                    "label": "First name",
                    "handle": "firstName",
                    "required": false
                  }
                ]
              }
            ]
          }
        ]
      }
    }
  }
}

# Querying a form field on a Craft Entry

You can query an Entry form field by using the form field name in the query: Assuming the form field's handle is myFormFieldHandle and the section is called Blog

query {
  entries {
    id
    title
    ...on blog_blog_Entry {
      myFormFieldHandle {
        id
        name
        fields {
          handle
          label
          type
        }
      }
    }
  }
}

Example response data:

{
  "data": {
    "entries": [
      {
        "id": "226",
        "title": "Some Entry title",
        "myFormFieldHandle": {
          "id": 1,
          "name": "Simple Form",
          "fields": [
            {
              "handle": "firstName",
              "label": "First Name",
              "type": "text"
            }
          ]
        }
      },
    ]
  }
}

# Form Query Arguments

The following arguments are available when querying single or multiple forms:

query {
  freeform {
    # This is just an example
    # For `id`, `uid` and `handle` - you can either pass a single value 
    # or an array of values for each argument
    form (id: 1, handle: "test", limit: 1, offset: 2, orderBy: "name", sort: "desc") {
      id
    }
  }
}

# Field Query Arguments

You can query fields by the following arguments:

query {
  freeform {
    forms {
      # This is just an example
      # You can either pass a single value or an array of values for each argument
      fields (id: [1, 2, 3], handle: ["firstName", "lastName"]) {
        id
        handle
      }
    }
  }
}

# Mutations

GraphQL mutations provide a way to modify data. The actual mutations will vary depending on the schema and what it allows. There are common mutations per GraphQL object type and additional type-specific mutations.

# Creating a new Submission

To create a new submission we use form-specific mutations in the form of save_<formHandle>_Submission.

Mutations take the data as arguments. We pass the values we want to use in the query as query variables.

In this example, we're using a form with the handle of contact which contains form fields for first name, last name and email. Our form also has Honeypot and ReCaptcha V3 enabled. We also pass some form property overrides, setting dynamic notification recipients.

You can grab these values using form-specific GraphQL queries or by creating an custom endpoint on your site.

See How to Render a Form.

// Query
mutation SaveContactSubmission(
    $formProperties: FreeformFormPropertiesInputType,
    $honeypot: FreeformHoneypotInputType,
    $captcha: FreeformSubmissionCaptchaInputType,
    $csrfToken: FreeformCsrfTokenInputType,
    $firstName: String,
    $lastName: String,
    $email: String,
) {
    save_contact_Submission(
        formProperties: $formProperties
        honeypot: $honeypot
        captcha: $captcha
        csrfToken: $csrfToken
        firstName: $firstName
        lastName: $lastName
        email: $email
    ) {
        submissionId
        success
    }
}

// Query Variables
{
    "formProperties": {
		"dynamicNotification": {
    	    "recipients": ["support@solspace.com", "user@solspace.com"], 
            "template": "new_template_1.twig"
  	    }
	}
    "honeypot": {
        "name": "freeform_form_handle",
        "value": ""
    }
    "captcha": {
        "name": "g-recaptcha-response",
        "value": "INSERT RECAPCTHA RESPONSE",
    },
    "csrfToken": {
        "name": "INSERT CSRF TOKEN NAME",
        "value": "INSERT CSRF TOKEN VALUE",
    },
    "firstName": "Solspace",
    "lastName": "Freeform",
    "email": "support@solspace.com"
}

Example response data:

{
    "data": {
        "save_contact_Submission": {
            "submissionId": 1982,
            "success": true,
        }
    }
}

# Submission Mutation Arguments

# Interfaces

# Form Interface

These are the fields available for the FreeformFormInterface:

# Field Interface

Use FreeformFieldInterface.

The base FreeformFieldInterface implemented by all field types. You can see specific Field Type fields here.

# Page Interface

Use FreeformPageInterface.

Each page contains a list of FreeformRowInterface objects:

# Row Interface

Use FreeformRowInterface.

Each row contains a list of fields:

# Submission Interface

These are the fields available for the FreeformSubmissionInterface:

# Option Interface

Use FreeformOptionInterface.

# Opinion Scale Interface

Use FreeformOpinionScaleInterface.

# Attributes Interface New in 5.0+

Use FreeformAttributesInterface.

# Attribute Interface

Use FreeformAttributeInterface.

# Honeypot Interface

Use FreeformHoneypotInterface.

# CSRF Token Interface

Use FreeformCsrfTokenInterface.

# Form Captcha Interface Renamed in 5.0+

Use FreeformFormCaptchaInterface.

# Submission Captcha Interface

Use FreeformSubmissionCaptchaInterface.

# Buttons Interface New in 5.0+

Use FreeformButtonsInterface.

# Buttons Attributes Interface New in 5.0+

Use FreeformButtonsAttributesInterface.

# Notification Template Interface New in 5.0+

Use FreeformNotificationTemplateInterface.

# Rules Interface New in 5.0+

Use FreeformRulesInterface.

# Page Rule Interface New in 5.0+

Use FreeformPageRuleInterface.

# Field Rule Interface New in 5.0+

Use FreeformFieldRuleInterface.

# Rule Condition Interface New in 5.0+

Use FreeformRuleConditionInterface.

# Form Properties Interface New in 5.0+

Use FreeformFormPropertiesInterface.

# Dynamic Notification Interface New in 5.0+

Use FreeformDynamicNotificationInterface.

# Field Types

# Text

fields {
  ... on FreeformField_Text {
    value
    placeholder
  }
}

# Textarea

fields {
  ... on FreeformField_Textarea {
    value
    rows
    placeholder
  }
}

# Dropdown

fields {
  ... on FreeformField_Dropdown {
    value
    options {
      value
      label
      checked
    }
  }
}

# Checkbox

fields {
  ... on FreeformField_Checkbox {
    value
    checked
  }
}

# Multi-Select

fields {
  ... on FreeformField_MultipleSelect {
    values
    options {
      value
      label
      checked
    }
  }
}

# Checkboxes

fields {
  ... on FreeformField_Checkboxes {
    values
    oneLine
    options {
      value
      label
      checked
    }
  }
}

# Radios

fields {
  ... on FreeformField_Radios {
    value
    options {
      value
      label
      checked
    }
  }
}

# Email

fields {
  ... on FreeformField_Email {
    placeholder
  }
}

# Number

fields {
  ... on FreeformField_Number {
    value
    minLength
    minValue
    maxValue
    decimalCount
    decimalSeparator
    thousandsSeparator
    allowNegative
    placeholder
  }
}

# File

fields {
  ... on FreeformField_File {
    fileKinds
    maxFileSizeKB
    fileCount
  }
}

# Confirmation

fields {
  ... on FreeformField_Confirmation {
    targetFieldHash
  }
}

# Date & Time

fields {
  ... on FreeformField_Datetime {
    value
    dateTimeType
    generatePlaceholder
    dateOrder
    date4DigitYear
    dateLeadingZero
    dateSeparator
    clock24h
    clockSeparator
    clockAMPMSeparate
    useDatepicker
    minDate
    maxDate
  }
}

# Opinion Scale

fields {
  ... on FreeformField_OpinionScale {
    value
    legends
    scales {
      value
      label
    }
  }
}

# Phone

fields {
  ... on FreeformField_Phone {
    value
    pattern
    useJsMask
  }
}

# Rating

fields {
  ... on FreeformField_Rating {
    value
    maxValue
    colorIdle
    colorHover
    colorSelected
  }
}

# Regex

fields {
  ... on FreeformField_Regex {
    value
    pattern
    message
  }
}

# Signature

fields {
  ... on FreeformField_Signature {
    width
    height
    showClearButton
    borderColor
    backgroundColor
    penColor
    penDotSize
  }
}

# Table

fields {
  ... on FreeformField_Table {
    useScript
    maxRows
    addButtonLabel
    addButtonMarkup
    removeButtonLabel
    removeButtonMarkup
    tableLayout
  }
}

# Submit

fields {
  ... on FreeformField_Submit {
    labelNext
    labelPrev
    disablePrev
    position
  }
}

# How to Render a Form

Below are the steps for being able to render your own form in the front-end using GraphQL data and another headless solution such as (but not limited to) Vue.js, Next.js, or React JS.

# Overview

To be able to make a form submittable you will need several things:

• An action entry in the POST payload that points to freeform/submit.
• A formHash entry which you will have to retrieve from an endpoint you create.
• A honeypot entry if you're using the Freeform Honeypot.
• A captcha entry if you're using the Freeform Captchas.
• A csrfToken entry if you're using Craft's CSRF tokens.
• A freeform_payload entry if you're using Encrypted Payload as the session storage type.

To get a valid formHash, honeypot, captcha, csrfToken and freeform_payload, you will have to create an endpoint on your site.

# Twig

If you're using Twig, here's how to return the form properties data:

{# You can attach custom form properties #}
{# https://docs.solspace.com/craft/freeform/v5/templates/queries/form/#parameters #}
{% set formProperties = {} %}
{% set form = freeform.form('your_form_handle', formProperties) %}

# PHP

If you're making your own endpoint via PHP, then we've outlined some simple steps to follow in order to set up a custom Freeform Module.

<?php

namespace modules;

use Craft;
use yii\base\Module;

class FreeformModule extends Module
{
    public function init()
    {
        Craft::setAlias('@modules', __DIR__);

        if (Craft::$app->getRequest()->getIsConsoleRequest()) {
            $this->controllerNamespace = 'modules\\console\\controllers';
        } else {
            $this->controllerNamespace = 'modules\\controllers';
        }

        parent::init();
    }
}

<?php

use modules\FreeformModule;

return [
    'modules' => [
        'freeform-module' => FreeformModule::class,
    ],
    'bootstrap' => ['freeform-module'],
];

<?php

namespace modules\controllers;

use craft\web\Controller;
use Solspace\Freeform\Freeform;
use yii\web\Response;

class FormController extends Controller
{
    protected array|bool|int $allowAnonymous = true;

    public function actionIndex(): string
    {
        return 'Welcome to the Craft Freeform Form Controller';
    }

    public function actionProperties(int $formId): Response
    {
        $form = Freeform::getInstance()->forms->getFormById($formId);

        if ($form) {
            return $this->asJson($form->toArray());
        }

        return $this->asJson(['message' => 'Form was not found']);
    }
}

<?php

return [
    'graphql/api' => 'graphql/api',
    'freeform/form' => 'freeform-module/form/index',
    'freeform/form/properties/<formId:\d+>' => 'freeform-module/form/properties',
];

{
    "id": 1,
    "hash": "xxxxxxxx-xxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "name": "My Form Handle",
    "handle": "my-form-handle",
    "class": "Solspace\\Freeform\\Form\\Types\\Regular",
    "enctype": "application\/x-www-form-urlencoded",
    "properties": {
        "hash": "YNkW4Jzye-O2Gd90zeo-tY6a9U8ihSaw0zdJ9yUKne7P7OiLNVnuMVi9Nf5v",
        "init-time": 1694603762,
        "secret": "F2okR1p8To6y1nAZaY5n"
    },
    "attributes": {
        "row": {},
        "success": {},
        "errors": {}
    },
    "settings": {
        "behavior": {
            "ajax": true,
            "showProcessingSpinner": true,
            "showProcessingText": true,
            "processingText": "Its Processing...",
            "successBehavior": "reload",
            "successTemplate": "successsample.twig",
            "returnUrl": "/",
            "successMessage": "Form has been submitted successfully!",
            "errorMessage": "Sorry, there was an error submitting the form. Please try again.",
            "duplicateCheck": "limit_once_per_email",
            "stopSubmissionsAfter": "2023-09-15T23:00:00.000000Z"
        },
        "general": {
            "name": "My Form Handle",
            "handle": "my-form-handle",
            "type": "Solspace\\Freeform\\Form\\Types\\Regular",
            "submissionTitle": "{{ dateCreated|date(\"Y-m-d H:i:s\") }}",
            "formattingTemplate": "basic-dark/index.twig",
            "description": "Test Form",
            "color": "#d0021b",
            "postForwardingUrl": "",
            "postForwardingErrorTriggerPhrase": "",
            "storeData": true,
            "defaultStatus": 3,
            "collectIpAddresses": true,
            "allowUsersToOptIn": true,
            "optInCheckbox": null
        }
    },
    "honeypot": {
        "name": "freeform_form_handle",
        "value": ""
    },
    // If using encrypted payloads:
    "freeform_payload": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "anchor": "xxxxxx-form-xxxxxxxx-xxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "csrf": {
        "name": "CRAFT_CSRF_TOKEN",
        "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    },
    "action": "freeform\/submit"
    // If using Captcha:
    "captcha": {
        "enabled": true,
        "handle": "captcha",
        "name": "g-recaptcha-response" // or h-captcha-response
    }
}

Have a look at our headless demos to get a feel for what's possible with GraphQL:

• VueJS + GraphQL implementations
• ReactJS + GraphQL implementations
• NextJS + GraphQL implementations