{"id":174,"date":"2021-05-06T19:07:42","date_gmt":"2021-05-07T01:07:42","guid":{"rendered":"https:\/\/developers.wpengine.com\/blog\/?p=174"},"modified":"2026-02-05T21:03:24","modified_gmt":"2026-02-06T03:03:24","slug":"gravity-forms-headless-wordpress","status":"publish","type":"post","link":"https:\/\/wpengine.com\/builders\/gravity-forms-headless-wordpress\/","title":{"rendered":"Gravity Forms in Headless WordPress"},"content":{"rendered":"\n

Gravity Forms<\/a> is one of the most popular premium form plugins for WordPress. It allows content creators to create a form, define which fields it should contain, render it to a page or post, and store form submissions. It also offers many extensions that provide additional features and integrations with many third-party services.<\/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 backend to send and receive Gravity Forms data to\/from a decoupled front-end React<\/a> application.<\/p>\n\n\n\n

I’ll provide a suite of React components, a React hook, and helper functions that you can even drop into your 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>, Next.js<\/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>, WPGraphQL<\/a> and WPGraphQL for Gravity Forms<\/a> WordPress plugins.<\/li>
  3. Clone down the Next.js 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 Next.js app’s folder and click the button to import it.<\/li>
  5. Create an .env.local<\/code> file inside of the Next.js app’s folder. Open that file in a text editor and paste in NEXT_PUBLIC_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 Apollo Client will use when it sends requests to your WordPress back-end.<\/li>
  6. Run npm install<\/code> or yarn<\/code> to install the dependencies.<\/li>
  7. Run npm run dev<\/code> to get the server running locally.<\/li>
  8. You should now be able to visit http:\/\/localhost:3000\/<\/a> in a web browser and see the “Welcome to Next.js!” page.<\/li><\/ol>\n\n\n\n

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

    The WPGraphQL for Gravity Forms plugin provides a gravityFormsForm<\/code> query that we can use to query for data about our Gravity Forms forms. Here’s a simple example:<\/p>\n\n\n

    query getForm {\n<\/span><\/span>   gravityFormsForm(id: 5, idType: DATABASE_ID) {\n<\/span><\/span>     formId\n<\/span><\/span>     title\n<\/span><\/span>     description\n<\/span><\/span>     formFields(first: 500) {\n<\/span><\/span>       nodes {\n<\/span><\/span>         ... on TextField {\n<\/span><\/span>           id\n<\/span><\/span>           type\n<\/span><\/span>           label\n<\/span><\/span>         }\n<\/span><\/span>         ... on SelectField {\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 WordPress admin. Here’s how:<\/p>\n\n\n\n
    1. Go to GraphQL<\/code> > GraphiQL IDE<\/code>.<\/li>
    2. Paste the query above into the left column, replacing id: 5<\/code> with the ID of the imported form.<\/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 gravityFormsForm<\/code>, as well as other queries and mutations the plugin offers.<\/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 front-end app.<\/p>\n\n\n\n
      Open up the Next.js app in a code editor, and open pages\/questionnaire.tsx<\/code>. Notice that we’re exporting a getStaticProps()<\/a><\/code> function from this file that calls an asynchronous getGravityForm()<\/code> function, passing in a form ID and returning the form data that comes back. Next.js then handles passing that form data into the Questionnaire<\/code> component.<\/p>\n\n\n\n
      Go ahead and swap out the form ID being passed into getGravityForm()<\/code> with the ID of the form you imported.<\/p>\n\n\n\n
      Now try navigating to http:\/\/localhost:3000\/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
      \"\"<\/figure>\n\n\n\n
      But where’s all this form data-fetching magic happening? Let’s dig a bit deeper. Open up utilities\/gravity-forms.tsx<\/code>. You’ll see that we’re defining const GET_FORM<\/code>, a gql<\/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
      const<\/span> GET_FORM = gql`<\/span>\n<\/span><\/span>  query getForm($formId: ID!) {<\/span>\n<\/span><\/span>    gravityFormsForm(id: $formId, idType: DATABASE_ID) {<\/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(first: 500) {<\/span>\n<\/span><\/span>        nodes {<\/span>\n<\/span><\/span>          id<\/span>\n<\/span><\/span>          type<\/span>\n<\/span><\/span>          ... on AddressField {<\/span>\n<\/span><\/span>            ...AddressFieldFields<\/span>\n<\/span><\/span>          }<\/span>\n<\/span><\/span>          ... on CheckboxField {<\/span>\n<\/span><\/span>            ...CheckboxFieldFields<\/span>\n<\/span><\/span>          }<\/span>\n<\/span><\/span>          ... on DateField {<\/span>\n<\/span><\/span>            ...DateFieldFields<\/span>\n<\/span><\/span>          }<\/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>  ${ADDRESS_FIELD_FIELDS}<\/span><\/span>\n<\/span><\/span>  ${CHECKBOX_FIELD_FIELDS}<\/span><\/span>\n<\/span><\/span>  ${DATE_FIELD_FIELDS}<\/span><\/span>\n<\/span><\/span>  # etc.<\/span>\n<\/span><\/span>`<\/span>;\n<\/span><\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
      These fields could<\/em> have all been hardcoded in the gravity-forms.tsx<\/code> file, but using GraphQL fragments allows us to co-locate the code that defines each field’s data requirements with the component responsible for rendering that field.<\/p>\n\n\n\n
      Lastly, check out the getGravityForm()<\/code> function definition. You can see that it calls Apollo Client’s client.query()<\/code> function, passing to it the getForm<\/code> query and the formId<\/code> as a variable. After the request finishes, it returns the form data.<\/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 pages\/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>{title}<\/h1<\/span>><\/span>\n<\/span><\/span>  <p<\/span>><\/span>{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 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 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 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 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 a GraphQL fragment (which gets used in utilities\/gravity-forms.tsx<\/code>, as we saw earlier)<\/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 components\/GravityForm.tsx<\/code>? That, and the custom useGravityForm()<\/code> hook are defined in 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 front-end 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
      For the formFields<\/code> > nodes<\/code> union, we’re making use of GraphQL fragments<\/a>. The fragments are imported from other field-specific files in the project and interpolated into our gql<\/code> template literal using the ${ADDRESS_FIELD_FIELDS}<\/code> syntax.<\/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