Using Gravity Forms with Headless WordPress and Next JS

This article was originally posted (and is more up to date) at https://robertmarshall.dev/blog/using-gravity-forms-with-headless-wordpress-and-next-js/

This article covers Next JS 13 with the app directory. That said, it could easily be ported to the pages structure.

It is possible to set up Gravity Forms yourself. Either creating the queries and mutations needed using WpGraphql. Passing data back to Gravity Forms using either native fetch or Apollo. If you aren’t a fan of GraphQL, you might want to use the built in GF Rest API.

However, why reinvent the wheel.

This article aims to introduce a far cleaner, simpler way of using Gravity Forms with Next JS. It will provide a step by step walkthrough of what is needed, as well as provide an example git repository so you can copy/paste.

TLDR

• Get WordPress ready
  • Install Gravity Forms
  • Install wp-graphql
  • Install wp-graphql-gravity-forms
• Add next-gravity-forms to your Next JS project.
• Example repo with solution: https://github.com/robmarshall/next-gravity-forms-example

Contents

• What Packages Do I Need?
  • WordPress
  • Next JS
• Step 1 – Setup WordPress
• Step 2 – Add Form Packages to Next JS
  • Add Package
  • Environment Variables
• Step 3 – Using the Package Within Your Project
  • Getting Gravity Form Data from WordPress to Next JS
• Add Google reCaptcha to the Form
• Styling the Next Gravity Forms Package

What Packages Do I Need?

We will use the following packages:

WordPress

• Gravity Forms
• wp-graphql
• wp-graphql-gravity-forms

Next JS

• next-gravity-forms

Step 1 – Setup WordPress

The first step is to get the WordPress site set up. This is pretty painless (much like the whole process TBH).

The below exposes your Gravity Forms forms using GraphQL, so the frontend (Next) can get the form shape, and pass back user submissions.

• Install and Activate Gravity Forms (get a license here if you need one)
• Install & activate WPGraphQL on your WordPress site – This can be installed from the plugin directory on your WordPress backend.
• Download zip from the wp-graphql-gravity-forms repository (download latest release as a zip from here) and upload it to your WordPress install. Then activate the plugin.

Step 2 – Add Form Packages to Next JS

Add Package

Now add Next Gravity Forms to your project.

# Use Yarn
yarn add next-gravity-forms

# Or NPM
npm i next-gravity-forms

Environment Variable

Now add the environment variable needed. Next-gravity-forms grabs this and uses it to send back user submissions.

NEXT_PUBLIC_WORDPRESS_API_URL=YOUR_ENDPOINT

Note

If your WordPress GraphQL data is passed through a cache like Stellate (if its not, I recommend them!), set NEXT_PUBLIC_WORDPRESS_API_URL with the cache URL, and add a secondary environment variable – NEXT_PUBLIC_WORDPRESS_FORM_SUBMIT_URL – to handle submissions.

This means you can still take advantage of any caching you may have set up, and bypass this when wanting to submit data. E.G.

NEXT_PUBLIC_WORDPRESS_API_URL=YOUR_CACHED_ENDPOINT
NEXT_PUBLIC_WORDPRESS_FORM_SUBMIT_URL=YOUR_DIRECT_ENDPOINT

Step 3 – Using the Package Within Your Project

Create Frontend Form Component

Next create a component for the client side code to live in.

This is because the form component itself contains React Hook Forms, a client side library. It needs wrapping in:

use client

The component will look something like this:

"use client";

import GravityFormForm from "next-gravity-forms";

const GravityForm = ({ form }) => <GravityFormForm data={form} />;

export default GravityForm;

Example in repository: https://github.com/robmarshall/next-gravity-forms-example/blob/main/components/GravityForm.js

Get Gravity Forms Data from WordPress into Next JS

Getting a Single Form

If you know the ID of the specific form you want to render, the setup is fairly simple.

import { getGravityForm } from "next-gravity-forms/server";
import GravityForm from "components/GravityForm";

export default async function Page() {
  const form = await getGravityForm(1);

  return <GravityForm form={form} />;
}

Note

getGravityForm is a server side function, it does not run on the client side. Make sure to only use it within a Server Component or within an API route.

Rendering Forms Dynamically

This is a little more complicated (but not massively). The complexity is introduced by the fact that we want to dynamically pick a form to render on the client side. But can only retrieve the specific form data on the server side.

This is solved by getting all forms (or a subset of them, if you only want to pick from X number of forms) and passing this collecting of data to the frontend.

Once the frontend has the form data, the specific forms data can be passed to the GravityFormForm component when needed.

Take a look at the dynamic example within the repository to see how this works.

Add Google reCaptcha to the Form

The next-gravity-forms package is built so that reCaptcha “just works”.

The only thing to check is that the reCaptcha details have been added to the Gravity Forms settings on the WordPress side.

Take a look at the Gravity Forms help article for more info: https://www.gravityforms.com/blog/add-recaptcha-to-your-forms/

Styling the Next Gravity Forms Package

There is no default styling currently packaged in with the next-gravity-forms package. This means that you will need to handle all the styling yourself.

The GravityFormForm component uses exactly the same CSS classes as the PHP Gravity Forms HTML. This means you can move your styling from a pre-existing WordPress site to Gatsby very easily. It doesn’t include support for CSS-in-JS/styled components yet.

There is baseline styling CSS file included in the example repo. This should get you to a point where you can see the form working.

Example form styling

Example repo with solution if you missed it in the article: https://github.com/robmarshall/next-gravity-forms-example

Hopefully this article has helped, and if you have any questions you can reach me at: @robertmars