What is Hygraph and how does it help with form creation in Next.js and GraphQL?
Hygraph is a GraphQL-native headless CMS that enables developers and content teams to dynamically build forms and capture submissions using Next.js and GraphQL. It provides a flexible content modeling system, allowing you to define custom form fields (Input, Textarea, Select, Checkbox) and manage form data efficiently. The platform supports union types, making it easy to associate different field types with forms and pages. Source
What form field types does Hygraph support for dynamic forms?
Hygraph supports several form field types for dynamic forms, including Input (with types TEXT, EMAIL, TEL), Textarea, Select (with multiple options), and Checkbox. These can be modeled and referenced in your content schema, allowing for flexible and customizable forms. Source
How does Hygraph handle form submissions and data storage?
Hygraph enables form submissions to be stored using a dedicated Submission model. Submitted data is saved in a JSON field called formData, and each submission is linked to the corresponding form via a reference field. This approach allows for flexible data management and easy integration with other services via webhooks. Source
Can I integrate Hygraph forms with external services like Zapier or Slack?
Yes, Hygraph supports webhooks that allow you to listen for new submissions and forward data to external services such as Zapier, Slack, or email. This enables automation and integration with your broader workflow without writing custom backend code. Source
Does Hygraph provide a GraphQL API for querying and managing content?
Yes, Hygraph offers a powerful GraphQL API for querying and managing content, including forms and submissions. The API supports advanced queries, mutations, and union types, making it highly flexible for developers. API Reference
What integrations are available with Hygraph?
Hygraph supports a wide range of integrations, including hosting and deployment (Netlify, Vercel), eCommerce (BigCommerce, commercetools, Shopify), localization (Lokalise, Crowdin, EasyTranslate, Smartling), digital asset management (Aprimo, AWS S3, Bynder, Cloudinary, Mux, Scaleflex Filerobot), personalization and AB testing (Ninetailed), artificial intelligence (AltText.ai), and more. Integrations List
Technical Requirements & Setup
How do I set up a Next.js project to work with Hygraph?
To set up a Next.js project with Hygraph, initialize a new Next.js app, install the graphql-request package for GraphQL queries, and configure your API endpoint and authentication tokens in environment variables. Hygraph provides step-by-step guides and code samples for integrating with Next.js. Source
How do I manage form state and submissions in Hygraph?
You can manage form state and submissions using libraries like react-hook-form in your Next.js application. Submitted data is sent to Hygraph via GraphQL mutations and stored in the Submission model. Hygraph's documentation provides detailed instructions and code samples for this process. Source
How do I connect form submissions to a specific form in Hygraph?
When submitting a form, use the createSubmission mutation and pass both the formData (the submitted values) and the formId to associate the submission with the correct form. This ensures each submission is linked to its originating form for easy management and retrieval. Source
How do I deploy my Next.js site with Hygraph forms?
You can deploy your Next.js site to Vercel by installing the Vercel CLI and running the vercel command in your project directory. Once deployed, your forms powered by Hygraph will be available at your deployment URL. Source
Security & Compliance
What security and compliance certifications does Hygraph have?
Hygraph is SOC 2 Type 2 compliant, ISO 27001 certified, and GDPR compliant. These certifications ensure enterprise-grade security and data protection for all users. Hygraph also offers features like SSO integrations, audit logs, encryption at rest and in transit, and sandbox environments. Security Features
Pricing & Plans
What is Hygraph's pricing model?
Hygraph offers a free forever Hobby plan, a Growth plan starting at $199/month, and custom Enterprise plans. For detailed pricing and feature breakdowns, visit the pricing page.
Use Cases & Benefits
Who can benefit from using Hygraph for forms and content management?
Hygraph is ideal for developers, IT decision-makers, content creators, project managers, agencies, and technology partners. It is especially beneficial for modern software companies, enterprises seeking to modernize their tech stack, and brands aiming to scale digital experiences across geographies. About Us
What business impact can I expect from using Hygraph?
Businesses using Hygraph can expect faster speed-to-market, reduced operational costs, streamlined workflows, and improved customer experience through scalable and consistent content delivery. Case studies show results such as 3X faster time to market (Komax) and a 20% increase in website monetization (Autoweb). Customer Stories
Support & Documentation
What support and documentation does Hygraph offer?
Hygraph provides comprehensive technical documentation, video tutorials, onboarding guides, and 24/7 support via chat, email, and phone. Enterprise customers receive dedicated onboarding and expert guidance. The community Slack channel is also available for peer support. Documentation | Contact
Customer Success & Case Studies
Can you share specific case studies or success stories of customers using Hygraph?
Yes, Hygraph has several notable customer success stories. For example, Komax achieved 3X faster time to market, Autoweb saw a 20% increase in website monetization, Samsung improved customer engagement, and Dr. Oetker enhanced their digital experience using MACH architecture. More case studies are available on the case studies page.
Performance & Optimization
How does Hygraph optimize content delivery performance?
Hygraph emphasizes optimized content delivery performance, which improves user experience, engagement, and search engine rankings. Rapid content distribution and responsiveness help reduce bounce rates and increase conversions. Performance Details
Before we dive into creating our schema, let's first think about what we're going to need to enable our marketing team to spin up landing page forms from just using the CMS.
It all starts with a Page. Pages must have a slug field so we can easily look up content from the params of any request.
Next, for simplicity, each page will have an associated Form model. For the sake of this tutorial, we'll pick 4 form field types;
Input
Textarea
Select
Checkbox
Form Fields
If we think of a traditional form, let's try and replace all of the data points we need to recreate a simple contact form like the following:
<labelfor="favFramework">What's your favorite framework?</label>
<selectid="favFramework">
<optionvalue="react">React</option>
<optionvalue="vue">Vue</option>
<optionvalue="angular">Angular</option>
<optionvalue="svelte">Svelte</option>
</select>
</div>
<div>
<labelfor="message">Message</label>
<textareaid="message"placeholder="Leave a message"/>
</div>
<div>
<labelfor="terms">
<inputid="terms"type="checkbox"/>
I agree to the terms and privacy policy.
</label>
</div>
<div>
<buttontype="submit">Submit</button>
</div>
</form>
In the above form, we have some <input />'s that are required, some which are of type email, tel and text, while the <select /> has no placeholder or is required.
Hygraph has support for GraphQL Union Types. This means we can define models for each of our form field types, and associate them to our Form model as one "has many" field.
Our schema will end up looking a little something like the following...
Models
Page
Title, String, Single line text, Required, and used as a Title
Slug, String, Slug, Required - Specify {title} as the template
Form, Reference to Form
You can use the Slug field type that automatically generates a slug based on your title. You'll need to set the template. to{title} to make this work. You can always override slugs.
Form
Page, Reference, Accepts multiple Page values
Fields, Reference, Accepts multiple FormInput, FormTextarea, FormSelect and FormCheckbox values
FormInput
Name, String, Single line text, and used as a Title
Type, Enum, FormInputType dropdown
Label, String, Single line text
Placeholder, Single line text
Required, Boolean
Form, Reference to Form
FormTextarea
Name, String, Single line text, and used as a Title
Label, String Single line text
Placeholder, String, Single line text
Required, Boolean
Form, Reference to Form
FormSelect
Name, String, Single line text, and used as a Title
Now we have an idea of how our content model looks like. Let's create the models and their associations with eachother inside Hygraph.
You'll need an account to continue. Sign up or head to the Dashboard.
Once logged in, head to the Schema editor by selecting Schema from the side.
Click + Add in the sidebar above default system Asset model.
Go ahead and create the 7 models above. Don't worry about creating relations just yet, you can do them all at once after creating the other fields.
#3. Create an example Page and Form with Fields as a content editor
So that we are able to query, and build our forms, we're going to need some content inside our models.
Inside the Dashboard, head to the Content editor by selecting Content from the side.
Select the Page model and click + Create New from the top right.
Give your page a title and slug. I'll call use Contact Us, and contact, respectively.
Now underneath Form, click Create and add a new form.
Inside the inline Form content editor, click on Create and add a new document.
From the dropdown, select FormInput.
Inside the inline FormInput content editor, enter a name, type , label and placeholder for your form field. I'll add the values Name, TEXT, Your name, Name and set required to true.
Now click Save and publish.
Repeat steps 5-8 to add additional fields.
🖐 To follow along with the rest of this tutorial, I will be using the following values for my fields...
3 x FormInput's
Name
Name: name
Type: TEXT
Label: Name
Placeholder: Your name
Required: true
Email
Name: email
Type: EMAIL
Label: Email
Placeholder: Your email
Required: true
Tel
Name: tel
Type: TEL
Label: Tel
Placeholder: Your contact no.
Required: false
1 x FormTextarea
Message
Name: message
Label: Message
Placeholder: Leave a message
Required: true
1 x FormCheckbox
Terms
Name: terms
Label: I agree to the terms and privacy policy.
Required: true
1 x FormSelect
The FormSelect is a little special because it also references another model FormSelect.
First, create your FormSelect document as usual, entering the following.
Favourite Framework
Name: favFramework
Label: What's your favorite frontend framework?
Required: false
Next below Options, click on Create and add a new formOption.
Now for each of our choices below, repeat the steps to "Create and add a new formOption", and provide the value/option for each:
react/React
vue/Vue
angular/Angular
svelte/Svelte
Finally, click Save and publish on this and close each of the inline editors, making sure to publish any unsaved changes along the way.
Now we have created our fields, we can now reorder them using the content editor. This may be useful if you decide to add or remove some fields later, you can order the fields exactly the way you want them to appear.
✨ Simply drag each of the Field rows into the order you want. ✨
Hygraph has a flexible permissions system, which includes enabling certain user groups to do actions, and most importantly restrict who can query what data.
For the purposes of querying data to build our pages and forms, we'll enable public API queries.
To do this, go to your project Settings.
Open the API Access page
Enable Content from stage Published under Public API permissions
Save ✨
That's it! You can test this works using the API Playground and selecting Environment: master Public from the dropdown in the section above your query/result.
🖐 Make sure to copy your API Endpoint to the clipboard. We'll need it in step 8.
This comes in two significant parts. First we create the routes (or "paths") and then query for the data for each page with those path params.
8.1 Create programmatic page routes
First up is to add some code to our Next.js application that will automatically generate pages for us. For this we will be exporting the getStaticPaths function from a new file called [slug].js in our pages directory.
touch pages/[slug].js
Having a filename with square brackets may look like a typo, but rest assured this is a Next.js convention.
Inside pages/[slug].js add the following code to get going:
exportdefaultfunctionIndex(props){
return(
<pre>{JSON.stringify(props,null,2)}</pre>
)
}
If you're familiar with React already, you'll notice we are destructuring props from the Index function. We'll be updating this later to destructure our individual page data, but for now, we'll show the props data on each of our pages.
Inside pages/[slug].js, let's import graphql-request and initialize a new GraphQLClient client.
🖐 You'll need your API Endpoint from Step 6 to continue.
Finally inside getStaticPaths we are returning paths for our pages, and a fallback. These build the dynamic paths inside the root pages directory, and each of the slugs will become pages/[slug].js.
The fallback is false in this example, but you can read more about using that here.
🖐 getStaticPaths alone does nothing, we need to next query data for each of the pages.
8.2 Query page data
Now we have programmatic paths being generated for our pages, it's now time to query the same data we did in step 5, but this time, send that data to our page.
Inside pages/[slug].js, export the following function:
Here we are destructuring the params object from the request sent to our page. The params here will be what we sent in getStaticPaths, so we'd expect to see slug here.
🖐 As well as destructuring, we are also renaming (or reassigning) the variable params to variables.
All we're doing in this file is importing each of our different form fields and exporting them.
The reason we do this is that when we import using import * as Fields, we can grab any of the named exports by doing Fields['FormCheckbox'], or Fields['FormInput'] like you see in components/Form.js.
Now that that we are importing these new fields, we next need to create each of them!
For each of the imports above, create new files inside components/FormFields for:
FormCheckbox.js
FormInput.js
FormSelect.js
FormTextarea.js
Once these are created, let's export each of the components as default, and write a minimum amount of code to make them work.
The code in the below files isn't too important. What's key about this tutorial is how we can very easily construct forms, and in fact any component or layout, using just data from the CMS. Magic! ✨
In this step we will install a library to handle our form state, and submissions, as well as create an onSubmit that'll we'll use in Step 12 to forward onto Hygraph.
Inside the terminal, let's install a new dependency:
yarn add -E react-hook-form # or npm install ...
Now it's not essential we use react-hook-form for managing our form, I wanted to provide a little closer to real world scenario than your typical setState example that are used in tutorials.
After we complete this tutorial, you should be in a position to return to each of your form fields, add some CSS, error handling, and more, made easy with react-hook-form!
Inside components/Form.js, add the following import to the top of the file:
Then inside your Form function after you return null if there are no fields, add the following:
const{ handleSubmit,...methods }=useForm();
constonSubmit=(values)=>console.log(values);
Finally, you'll need to wrap the current <form> with <FormContext {...methods}>, and add a onSubmit prop to the <form> that is onSubmit={handleSubmit(onSubmit)}.
Your final components/Form.js should look like this:
🖐 Let's start the Next.js development server, and view the console when we submit the form!
yarn dev # or npm run dev
Once the server has started, head to http://localhost:3000/contact (or a slug you defined in the CMS) to see your form!
Open the browser developer tools console, and then fill out the form and click submit!
You should now see the form values submitted!
#12. Submitting our Form to Hygraph with GraphQL Mutations
It's now time to take our form to the next level. We are going to update our Hygraph schema with a new Submission model that will be used to store submissions.
Inside the Hygraph Schema Editor, click + Add to create a new model.
Give the model a name of Submission,
Add a new JSON Editor field with the Display Name Form Data, and, API ID as formData,
Add a new Reference field with the Display Name/API ID Form/form , and select Form as the Model that can be referenced,
Configure the reverse field to Allow multiple values and set the default Display Name/API ID to (Submissions/submissions) respectively.
Things should look a little something like the following:
And the Form model should now have a new field submisson:
Since we want full control via the CMS what appears on our form, we'll just save all of that data inside formData JSON field.
🖐 Using something like webhooks would enable you to forward formData onto a service like Zapier, and do what you need to with the data, all without writing a single line of code! ✨
In order to use the Mutations API, we'll need to configure our API access to permit mutations and create a dedicated Permanent Auth Token. Don't enable Mutations for the Public API, as anybody will be able to query/mutate your data!
Head to Settings > API Access > Permanent Auth Tokens and create a token with the following setup:
Next, Copy the token to the clipboard once created.
Inside of the root of your Next.js project, create the file .env and, add the following, replacing YOUR_TOKEN_HERE with your token:
HYGRAPH_MUTATION_TOKEN=YOUR_TOKEN_HERE
With this token added, let's also do some housekeeping. Replace the API Endpoint you created in/pages/[slug].js with a the .env variable HYGRAPH_ENDPOINT and assign the value inside .env:
Now before we can use the HYGRAPH_MUTATION_TOKEN, we'll need to update our components/Form/index.js to POST the values to a Next.js API route.
Inside the form, let's do a few things:
import useState from React,
Invoke useState inside your Form function,
Replace the onSubmit function,
Render error after the submit <button />
import{ useState }from'react'
// ...
exportdefaultfunctionForm({ fields }){
if(!fields)returnnull;
const[success, setSuccess]=useState(null);
const[error, setError]=useState(null);
// ...
constonSubmit=async(values)=>{
try{
const response =awaitfetch("/api/submit",{
method:"POST",
body:JSON.stringify(values),
});
if(!response.ok)
thrownewError(`Something went wrong submitting the form.`);
setSuccess(true);
}catch(err){
setError(err.message);
}
};
if(success)return<p>Form submitted. We'll be in touch!</p>;
return(
// ...
<buttontype="submit">Submit</button>
{error &&<span>{error}</span>}}
)
}
Finally we'll create the API route /api/submit that forwards requests to Hygraph securely. We need to do this to prevent exposing our Mutation Token to the public.
One of the best ways to scaffold your mutation is to use the API Playground inside your Hygraph project. It contains all of the documentation and types associated with your project/models.
If you've followed along so far, the following mutation is all we need to create + connect form submissions.
Now go ahead and submit the form, open the content editor and navigate to the Submission content.
You should see your new entry!
You could use Hygraph webhooks to listen for new submissions, and using another API route forward that onto a service of your choice, such as email, Slack or Zapier.
Now all that's left to do is deploy our Next.js site to Vercel. Next.js is buil, and managed by the Vercel team and the community.
To deploy to Vercel, you'll need to install the CLI.
npm i -g vercel # or yarn global add vercel
Once installed, all it takes to deploy is one command!
vercel # or vc
You'll next be asked to confirm whether you wish to deploy the current directory, and what the project is named, etc. The defaults should be enough to get you going! 😅
Once deployed, you'll get a URL to your site. Open the deployment URL and append /contact to see your form!
Jamie is a software engineer turned developer advocate. Born and bred in North East England, he loves learning and teaching others through video and written tutorials. Jamie currently publishes Weekly GraphQL Screencasts.
Share with others
Sign up for our newsletter!
Be the first to know about releases and industry news and insights.