Using Gravity Forms with Headless WordPress and Next JS

Last Updated:
Brand logos for WordPress Gravity Forms and Next JS

This post contain affiliate links to Udemy courses, meaning when you click the links and make a purchase, I receive a small commission. I only recommend courses that I believe support the content, and it helps maintain the site.

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.



What Packages Do I Need?

We will use the following packages:


Next JS

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.



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.


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:

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} />;

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:

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:

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

Related Posts

Helpful Bits Straight Into Your Inbox

Subscribe to the newsletter for insights and helpful pieces on React, Gatsby, Next JS, Headless WordPress, and Jest testing.