{"id":211,"date":"2021-06-14T13:44:04","date_gmt":"2021-06-14T19:44:04","guid":{"rendered":"https:\/\/developers.wpengine.com\/blog\/?p=211"},"modified":"2026-02-05T21:01:37","modified_gmt":"2026-02-06T03:01:37","slug":"gravity-forms-in-headless-wordpress-gatsby","status":"publish","type":"post","link":"https:\/\/wpengine.com\/builders\/gravity-forms-in-headless-wordpress-gatsby\/","title":{"rendered":"Gravity Forms in Headless WordPress with Gatsby"},"content":{"rendered":"\n

A couple weeks ago, I wrote a Gravity Forms in Headless WordPress<\/a> blog post, and recorded a YouTube video<\/a> to accompany it. They were both well received, but several members of the headless WordPress community told me that they’d love to learn how to work with Gravity Forms<\/a> in a Gatsby<\/a> app, specifically.<\/p>\n\n\n\n

In this post, we’ll learn how we can use WPGraphQL<\/a>, and WPGraphQL for Gravity Forms<\/a> on a headless WordPress back-end to send and receive Gravity Forms data to\/from a decoupled front-end Gatsby application. We’ll see how we can use the unified GraphQL data layer that Gatsby provides to query for our form data at buildtime, then use Apollo Client to submit form entries from the client.<\/p>\n\n\n\n

In the Gatsby app repo<\/a>, I’ll provide a suite of React components and a React hook that you can even drop into your Gatsby projects and have Gravity Forms “just work.” They’ll handle rendering out Gravity Forms forms and sending form submissions to your headless WordPress back-end.<\/p>\n\n\n\n

Let’s roll! \ud83c\udfce\ud83d\udca8<\/p>\n\n\n\n

Getting Started<\/h2>\n\n\n\n

To benefit from this post, you should be familiar with the basics of working with the command line, local WordPress<\/a> development, React<\/a>, Gatsby<\/a>, and Apollo Client<\/a>.<\/p>\n\n\n\n

Here are the steps for getting set up:<\/p>\n\n\n\n

  1. Set up a local WordPress site and get it running<\/li>
  2. Install and activate the Gravity Forms<\/a>, WPGatsby<\/a>, WPGraphQL<\/a> and WPGraphQL for Gravity Forms<\/a> WordPress plugins.<\/li>
  3. Clone down the Gatsby app repo<\/a> for this project.<\/li>
  4. Import the form questionnaire form. From the WordPress admin sidebar, go to Forms<\/code> > Import\/Export<\/code> > Import Forms<\/code>. Select the gravityforms-questionnaire-form.json<\/code> inside Gatsby app’s folder and click the button to import it.<\/li>
  5. Create an .env.development<\/code> file inside of the Gatsby app’s folder. Open that file in a text editor and paste in GATSBY_WORDPRESS_API_URL=http:\/\/wpgraphqlgravtyforms.local\/graphql<\/code>, replacing wpgraphqlgravtyforms.local<\/code> with the domain for your local WordPress site. This is the endpoint that both Gatsby and Apollo Client will use when they send requests to your WordPress back-end.<\/li>
  6. Run npm install<\/code> or yarn<\/code> to install the dependencies.<\/li>
  7. Run npm run develop<\/code> to get the server running locally.<\/li>
  8. You should now be able to visit http:\/\/localhost:8000\/<\/a> in a web browser and see the app’s homepage.<\/li><\/ol>\n\n\n\n

    How to Query for a Form<\/h2>\n\n\n\n

    The gatsby-source-wordpress<\/a> source plugin used by our app takes the GraphQL schema that WPGraphQL and WPGraphQL for Gravity Forms provide and adds it to Gatsby’s unified GraphQL data layer. So querying for a form looks like this:<\/p>\n\n\n

    query getForm {\n<\/span><\/span>  wpGravityFormsForm(formId: {eq: 4}) {\n<\/span><\/span>    formId\n<\/span><\/span>    title\n<\/span><\/span>    description\n<\/span><\/span>    formFields {\n<\/span><\/span>      nodes {\n<\/span><\/span>        id\n<\/span><\/span>        type\n<\/span><\/span>        ... on WpTextField {\n<\/span><\/span>          id\n<\/span><\/span>          type\n<\/span><\/span>          label\n<\/span><\/span>        }\n<\/span><\/span>        ... on WpSelectField {\n<\/span><\/span>          id\n<\/span><\/span>          type\n<\/span><\/span>          label\n<\/span><\/span>          choices {\n<\/span><\/span>            text\n<\/span><\/span>            value\n<\/span><\/span>          }\n<\/span><\/span>        }\n<\/span><\/span>      }\n<\/span><\/span>    }\n<\/span><\/span>  }\n<\/span><\/span>}\n<\/span><\/span><\/code><\/span><\/pre>\n\n\n
    We can test out this query right from the GraphiQL IDE that Gatsby provides. Here’s how:<\/p>\n\n\n\n
    1. With the app running, head over to http:\/\/localhost:8000\/___graphql<\/a>.<\/li>
    2. Paste the query above into the left column, replacing “4” in eq: 4<\/code> with the ID of the form you imported.<\/li>
    3. Click the \u25b6 button to execute the query.<\/li>
    4. See the results returned in the right column.<\/li><\/ol>\n\n\n\n
      \"\"<\/figure>\n\n\n\n
      Check out the WPGraphQL for Gravity Forms readme<\/a> for more documentation on this query, as well as other queries and mutations the plugin offers. Just note that many of the fields will have different names and input fields (such as wpGravityFormsForm<\/code> instead of gravityFormsForm<\/code>). That’s because Gatsby modifies the WPGraphQL schema a bit before adding it to its unified GraphQL data layer schema.<\/p>\n\n\n\n
      Query for a Form in our App<\/h2>\n\n\n\n
      Now that we know what a query for a form looks like let’s see how we can use it in our Gatsby app.<\/p>\n\n\n\n
      Open up gatsby-node.js<\/code>.<\/p>\n\n\n
      const<\/span> path = require<\/span>(\"path\"<\/span>);\n<\/span><\/span>\n<\/span><\/span>exports.createPages = async<\/span> ({ actions }) => {\n<\/span><\/span>  const<\/span> { createPage } = actions;\n<\/span><\/span>  const<\/span> questionnaireTemplate = path.resolve(`src\/templates\/questionnaire.tsx`<\/span>);\n<\/span><\/span>\n<\/span><\/span>  \/\/ Create Questionnaire page, and pass the Gravity Forms form ID to it.<\/span>\n<\/span><\/span>  createPage({\n<\/span><\/span>    path<\/span>: `\/questionnaire`<\/span>,\n<\/span><\/span>    component<\/span>: questionnaireTemplate,\n<\/span><\/span>    context<\/span>: {\n<\/span><\/span>      formId<\/span>: 4<\/span>,\n<\/span><\/span>    },\n<\/span><\/span>  });\n<\/span><\/span>};\n<\/span><\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
      Notice that we call the createPage()<\/code> function to tell Gatsby to create a page at \/questionnaire<\/code> using the src\/templates\/questionnaire.tsx<\/code> template, and that we pass in a formId<\/code> of 4<\/code> for the component’s context.<\/p>\n\n\n\n
      Go ahead and swap out this form ID with the ID of the form you imported.<\/p>\n\n\n\n
      \"Screenshot<\/figure>\n\n\n\n
      But where’s all this form data-fetching magic happening? Let’s dig a bit deeper. Open up the src\/templates\/questionnaire.tsx<\/code>. page template.<\/p>\n\n\n
      export<\/span> default<\/span> function<\/span> Questionnaire<\/span>({ data }: Props<\/span>) <\/span>{\n<\/span><\/span>  const<\/span> { wpGravityFormsForm<\/span>: form } = data;\n<\/span><\/span>\n<\/span><\/span>  return<\/span> (\n<\/span><\/span>    <main<\/span>><\/span><\/span>\n<\/span><\/span>      <h1<\/span>><\/span>{form.title}<\/h1<\/span>><\/span><\/span><\/span>\n<\/span><\/span>      <p<\/span>><\/span>{form.description}<\/p<\/span>><\/span><\/span><\/span><\/span><\/span>\n<\/span><\/span>      <GravityForm<\/span> form<\/span>={form}<\/span> \/><\/span><\/span><\/span><\/span><\/span><\/span><\/span>\n<\/span><\/span>    <\/main<\/span>><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span>\n<\/span><\/span>  );<\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span>\n<\/span><\/span>}<\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span>\n<\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span>\n<\/span><\/span>export<\/span> const<\/span> query = graphql`<\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span>\n<\/span><\/span>  query getForm($formId: Int!) {<\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span>\n<\/span><\/span>    wpGravityFormsForm(formId: { eq: $formId }) {<\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span>\n<\/span><\/span>      ...GravityFormFields<\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span>\n<\/span><\/span>    }<\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span>\n<\/span><\/span>  }<\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span>\n<\/span><\/span>`<\/span>;<\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span>\n<\/span><\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
      You’ll see that we’re exporting a graphql<\/code> tagged template literal containing our getForm<\/code> GraphQL query. It accepts formId<\/code> as an argument, then fetches the form with that ID.<\/p>\n\n\n\n
      The ...GravityFormFields<\/code> syntax makes use of this GraphQL fragment defined in src\/components\/GravityFormsForm.tsx<\/code>:<\/p>\n\n\n
      export<\/span> const<\/span> GRAVITY_FORM_FIELDS = graphql`<\/span>\n<\/span><\/span>  fragment GravityFormFields on WpGravityFormsForm {<\/span>\n<\/span><\/span>    formId<\/span>\n<\/span><\/span>    title<\/span>\n<\/span><\/span>    description<\/span>\n<\/span><\/span>    button {<\/span>\n<\/span><\/span>      text<\/span>\n<\/span><\/span>    }<\/span>\n<\/span><\/span>    confirmations {<\/span>\n<\/span><\/span>      isDefault<\/span>\n<\/span><\/span>      message<\/span>\n<\/span><\/span>    }<\/span>\n<\/span><\/span>    formFields {<\/span>\n<\/span><\/span>      nodes {<\/span>\n<\/span><\/span>        id<\/span>\n<\/span><\/span>        type<\/span>\n<\/span><\/span>        ...AddressFieldFields<\/span>\n<\/span><\/span>        ...CheckboxFieldFields<\/span>\n<\/span><\/span>        # etc.<\/span>\n<\/span><\/span>      }<\/span>\n<\/span><\/span>    }<\/span>\n<\/span><\/span>  }<\/span>\n<\/span><\/span>`<\/span>;\n<\/span><\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
      It specifies what data we want to fetch for the form. Inside, it leverages even more fragments\u2013 one for each type of field. You can see those individual field fragments in each file inside of the src\/components\/GravityFormsFields<\/code> folder.<\/p>\n\n\n\n
      These GraphQL fields could<\/em> have all been hardcoded in the src\/templates\/questionnaire.tsx<\/code> file, but using GraphQL fragments allows us to co-locate each component’s data requirements with that component itself. That way, things are more organized.<\/p>\n\n\n\n
      Render the Form<\/h2>\n\n\n\n
      Now that we know how the form data is being queried and passed into the Questionnaire<\/code> page component, let’s see how we can use that data to render our form.<\/p>\n\n\n\n
      Head back over to src\/templates\/questionnaire.tsx<\/code>. You’ll see that the form’s title<\/code> and description<\/code> render inside of h1<\/code> and p<\/code> tags, respectively, and then a <GravityForm \/><\/code> component is rendered, with the form<\/code> passed to it as a prop:<\/p>\n\n\n
      <main<\/span>><\/span>\n<\/span><\/span>  <h1<\/span>><\/span>{form.title}<\/h1<\/span>><\/span>\n<\/span><\/span>  <p<\/span>><\/span>{form.description}<\/p<\/span>><\/span>\n<\/span><\/span>  <GravityForm<\/span> form<\/span>={form}<\/span> \/><\/span>\n<\/span><\/span><\/main<\/span>><\/span>\n<\/span><\/span><\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n
      Open src\/components\/GravityForm.tsx<\/code>, where the GravityForm<\/code> component is defined, and you’ll see that it renders a GravityFormsForm<\/code> component, which is wrapped in a GravityFormProvider<\/code> context provider:<\/p>\n\n\n
      <GravityFormProvider<\/span>><\/span>\n<\/span><\/span>  <GravityFormsForm<\/span> {...props<\/span>} \/><\/span>\n<\/span><\/span><\/GravityFormProvider<\/span>><\/span>\n<\/span><\/span><\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n
      Don’t worry about GravityFormProvider<\/code> just yet\u2013 we’ll learn about that in the next section. For now, let’s focus on the GravityFormsForm<\/code> component rendered inside of it. Navigate to src\/components\/GravityFormsForm.tsx<\/code> next.<\/p>\n\n\n\n
      GravityFormsForm<\/code> accepts form<\/code> as a prop and renders an HTML <form><\/code> element with the form fields, any error messages, and the submit button inside. You’ll notice that it also contains a handleSubmit<\/code> function to serve as the onSubmit<\/code> event handler for our form. When the form is submitted, the submitForm<\/code> mutation (defined at the top of the file) executes with formId<\/code> and fieldValues<\/code> passed in as variables.<\/p>\n\n\n\n
      Next, let’s take a look at how our fields are rendering. Inside of the <form><\/code>, we map over the formFields<\/code> and render a GravityFormsField<\/code> component for each field:<\/p>\n\n\n
      {formFields.map(field<\/span> =><\/span>\n<\/span><\/span>  <GravityFormsField<\/span><\/span><\/span>\n<\/span><\/span>    key<\/span>={field?.id}<\/span><\/span><\/span>\n<\/span><\/span>    field<\/span>={field<\/span> as<\/span> FormField<\/span>}<\/span><\/span>\n<\/span><\/span>    fieldErrors<\/span>={getFieldErrors(Number(field?.id))}<\/span><\/span><\/span>\n<\/span><\/span>  \/><\/span><\/span>\n<\/span><\/span>)}\n<\/span><\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
      Let’s keep following this trail and head over to src\/components\/GravityFormsField.tsx<\/code> to check out the GravityFormsField<\/code> component. You’ll see that it’s little more than a switch()<\/code> statement:<\/p>\n\n\n
      export<\/span> default<\/span> function<\/span> GravityFormsField<\/span>({ field, fieldErrors }: Props<\/span>) <\/span>{\n<\/span><\/span>  switch<\/span> (field.type) {\n<\/span><\/span>    case<\/span> \"address\"<\/span>:\n<\/span><\/span>      return<\/span> <AddressField<\/span> field<\/span>={field}<\/span> fieldErrors<\/span>={fieldErrors}<\/span> \/><\/span><\/span>;\n<\/span><\/span>    case<\/span> \"checkbox\"<\/span>:\n<\/span><\/span>      return<\/span> <CheckboxField<\/span> field<\/span>={field}<\/span> fieldErrors<\/span>={fieldErrors}<\/span> \/><\/span><\/span>;\n<\/span><\/span>    case<\/span> \"date\"<\/span>:\n<\/span><\/span>      return<\/span> <DateField<\/span> field<\/span>={field}<\/span> fieldErrors<\/span>={fieldErrors}<\/span> \/><\/span><\/span>;\n<\/span><\/span>    \/\/ etc.<\/span>\n<\/span><\/span>  }\n<\/span><\/span>}\n<\/span><\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
      The appropriate field component is rendered out, depending on the value of field.type. <\/code>When field.type<\/code> encounters an unsupported field, a “Field type not supported” message appears instead.<\/p>\n\n\n\n
      Render the Fields<\/h2>\n\n\n\n
      From here, you can peruse all of the individual field components inside of the src\/components\/GravityFormsFields<\/code> folder to see how they work. All of them follow the same pattern. They:<\/p>\n\n\n\n
      1. Define their data requirements in an exported GraphQL fragment (which get leveraged inside of src\/components\/GravityFormsForm.tsx<\/code>, as mentioned previously)<\/li>
      2. Define the field component, which accepts these props:
        – field<\/code> (the data about this field)
        – fieldErrors<\/code> (any errors specific to this field)
        …and returns JSX for the field<\/li>
      3. Use the useGravityForm()<\/code> custom React hook and 
        – Use its state<\/code> object to get the current value for this field
        – Call its dispatch<\/code> function to update the field’s value in state
        <\/li><\/ol>\n\n\n\n
        “Wait, where in blazes did this custom useGravityForm()<\/code> React hook come from?!”<\/p>\u2013 You, just now<\/cite><\/blockquote>\n\n\n\n
        I’m glad you asked! Let’s find out \u2013<\/p>\n\n\n\n
        Managing our Form State<\/h2>\n\n\n\n
        Remember earlier when we saw that GravityFormProvider<\/code> context provider in src\/components\/GravityForm.tsx<\/code>? That, and the custom useGravityForm()<\/code> hook are defined in src\/hooks\/useGravityForm.tsx<\/code>. Let’s take a look at that file next to understand better how to manage our form state.<\/p>\n\n\n\n
        Scroll down to GravityFormProvider<\/code>. This is a React context provider that uses React’s useReducer()<\/code> and passes down state<\/code> and dispatch<\/code> as its value:<\/p>\n\n\n
        export<\/span> function<\/span> GravityFormProvider<\/span>({ children }: { children: ReactNode }<\/span>) <\/span>{\n<\/span><\/span>  const<\/span> [state, dispatch] = useReducer(reducer, DEFAULT_STATE);\n<\/span><\/span>\n<\/span><\/span>  return<\/span> (\n<\/span><\/span>    <GravityFormContext.Provider<\/span> value<\/span>={{<\/span> state<\/span>, dispatch<\/span> }}><\/span><\/span>\n<\/span><\/span>      {children}<\/span><\/span>\n<\/span><\/span>    <\/GravityFormContext.Provider<\/span>><\/span><\/span><\/span>\n<\/span><\/span>  );<\/span><\/span><\/span>\n<\/span><\/span>}<\/span><\/span><\/span>\n<\/span><\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
        When dispatch()<\/code> is called from inside of our field components, the reducer()<\/code> function in this file determines how the form state should update. The reducer runs a switch()<\/code> on the type of action that was dispatched and updates the form state accordingly using the action.fieldValue<\/code> data that passed in:<\/p>\n\n\n
        switch<\/span> (action.type) {\n<\/span><\/span>  case<\/span> ACTION_TYPES.updateAddressFieldValue: {\n<\/span><\/span>    const<\/span> { id, addressValues } = action.fieldValue as<\/span> AddressFieldValue;\n<\/span><\/span>    return<\/span> [...getOtherFieldValues(id), { id, addressValues }];\n<\/span><\/span>  }\n<\/span><\/span>  case<\/span> ACTION_TYPES.updateCheckboxFieldValue: {\n<\/span><\/span>    const<\/span> { id, checkboxValues } = action.fieldValue as<\/span> CheckboxFieldValue;\n<\/span><\/span>    return<\/span> [...getOtherFieldValues(id), { id, checkboxValues }];\n<\/span><\/span>  }\n<\/span><\/span>  \/\/ etc.<\/span>\n<\/span><\/span>}\n<\/span><\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
        Submitting Forms<\/h2>\n\n\n\n
        Try submitting a few form entries yourself. After the form submits, it will be removed from the UI and replaced with the “thank you” confirmation message for our form.<\/p>\n\n\n\n
        Back in the WordPress admin, you can navigate to the Gravity Forms Entries page for our form and see your new entries listed. Try clicking on a few of them and confirming that the saved values match what you had entered into the form.<\/p>\n\n\n\n
        Error Handling<\/h2>\n\n\n\n
        Our Gatsby app handles two types of errors:<\/p>\n\n\n\n
        Request or Server Errors<\/h3>\n\n\n\n
        These are errors that prevent the form entry from being saved. Some examples:<\/p>\n\n\n\n
      Now try restarting the local dev server, then navigating to http:\/\/localhost:8000\/questionnaire<\/a>. You should see the form’s title, description and fields displayed in all their barely-even-styled-at-all glory! ????<\/p>\n\n\n\n
    You can see that we’re asking for some data about the form itself; namely, its formId<\/code>, title<\/code> and description<\/code>. Then under formFields<\/code> > nodes<\/code> (which is a GraphQL interface<\/a>), we use the ... on<\/code> syntax to tell GraphQL what data we’d like back for each type of field. Any field types we include here will have data returned if they exist in the form, and any we have omitted will not\u2013 they’ll appear as empty objects instead.<\/p>\n\n\n\n