Integrate Formium with Next.js

Next.js is an exceptional tool for building modern, universal web applications with React.

Vercel, the company behind Next.js, is the easiest way to deploy a production-ready highly available Next.js website, with static assets being served through the CDN automatically and built-in support for Next.js' automatic static optimization, API routes, and preview mode.

Get Started

If you're starting a brand new project, you can clone one of the Next.js quickstarts or create a new one using the command below. If you already have a Next.js application, you can skip this step move to installation instructions.

npx create-next-app my-app

You'll be prompted to select a starter template. Choose the default one (or the one of your choice).

This will bootstrap the default Next.js template and install its dependencies. When it's finished, follow the instructions and navigate to the new directory (i.e. cd my-app). If you installed the default template, you're directory will look like this:

.
├── .gitignore        # Git ignore file
├── README.md         # Next.js instructions
├── package.json
├── pages             # Next.js pages directory
│   ├── api           # Next.js API Routes directory
│   │   └── hello.js  # Next.js example API Route
│   └── index.js      # Next.js Page component
├── public            # Next.js public static file directory
│   ├── favicon.ico
│   └── vercel.svg
└── yarn.lock

Install Formium dependencies

In order to use Formium, you'll need the Formium API client and Formium React packages. You'll use them to fetch your form schema, render your forms in React, and finally send your submission data back to Formium.

You can install both packages from NPM.

npm install @formium/client @formium/react

Add your credentials

In order to use the client, you need to gather your project credentials and expose them to Next.js. As of Next.js 9.5, you can use .env files to set environment variables.

Create a file named .env in the root of your Next.js project and add the following two lines:

NEXT_PUBLIC_FORMIUM_PROJECTID=XXXXX
FORMIUM_TOKEN=XXXXX

You'll need to replace the two XXXXXs in your .env.local file with the correct values for your specific Formium project and account. Here's how to get them:

• NEXT_PUBLIC_FORMIUM_PROJECTID - This is your project's public unique identifier. Go to the Formium dashboard, navigate to any of your project's form's Overview pages. Copy the Project ID from the API Information panel.

  

• FORMIUM_TOKEN - A secret personal access token to your account. You can create one in your Formium account settings here: https://dashboard.formium.io/account#tokens.

  

Now that you've setup your credentials, you can move on to initialize the Formium client in your codebase.

Setup the Formium Client

Create a new file named ./lib/formium.js in your project with the following code:

import { createClient } from '@formium/client';
export const formium = createClient(process.env.NEXT_PUBLIC_FORMIUM_PROJECTID, {
  apiToken: process.env.FORMIUM_TOKEN,
});

The Formium client is how your application communicates with the Formium API. It will allow you to fetch your form's schema and also capture submission data.

Fetch your form's schema

Next.js provides two primary ways to securely fetch data:

• getStaticProps is for fetching data at build time
• getServerSideProps is for fetching data on each request

We'll use getStaticProps for now to fetch our schemas at build time.

Inside of any page component in your Next.js project, import the Formium client you just created. Use the client's getFormBySlug method within getStaticProps to retrieve your Formium form's schema and return it as props.

import React from react;
import { formium } from '../lib/formium';
export async function getStaticProps(context) {
  // You can find your form's slug in the API Information panel
  // on your form's Overview page in the dashboard.
  const form = await formium.getFormBySlug('your_form_slug');
  return { props: { form } };
}
// Your formium form is now available as a prop
export default function MyPage({ form }) {
  console.log(form) // Check your console to ensure you're fetching data
  return (
    <div>
      <h1>My first Formium form</h1>
    </div>
  )
}

Render your form

Now that you have your form's data structure in Next.js, you can render it anywhere on your page using the <FormiumForm /> component from the @formium/react package. This is a special React component we've built that interprets your form's schema and renders it as well as coordinates validation, conditional logic, and submission handling.

import React from react;
import { formium } from '../lib/formium';
import { FormiumForm } from '@formium/react';
export async function getStaticProps(context) {
  const form = await formium.getFormBySlug('your_form_slug');
  return { props: { form } };
}
export default function MyPage({ form }) {
  return (
    <div>
      <h1>My first Formium form</h1>
      <FormiumForm data={form} />
    </div>
  );
}

Submit form data

The <FormiumForm /> component provides an onSubmit callback function for handling submission data. Together with the Formium client, use it to send data back to the Formium API for storage and processing.

import React from 'react';
import { formium } from '../lib/formium';
import { FormiumForm } from '@formium/react';
export async function getStaticProps(context) {
  const form = await formium.getFormBySlug('your_form_slug');
  return { props: { form } };
}
export default function MyPage({ form }) {
  return (
    <div>
      <h1>My first Formium form</h1>
      <FormiumForm
        data={form}
        onSubmit={async (values) => {
          // Send form values to Formium
          await formium.submitForm('your_form_slug', values);
          alert('Success');
        }}
      />
    </div>
  );
}

Bonus: Show a success message

Showing a success message helps the user know that their response has been received successfully. Within your onSubmit callback, you can either use regular React to set some state or use Next.js's router to navigate the user to a different page (with a success message on it).

import React from 'react';
import { formium } from '../lib/formium';
import { FormiumForm } from '@formium/react';
export async function getStaticProps(context) {
  const form = await formium.getFormBySlug('your_form_slug');
  return { props: { form } };
}
export default function MyPage({ form }) {
  const [success, setSuccess] = React.useState(false);
  if (success) {
    return <div>Thank you! Your response has been recorded.</div>;
  }
  return (
    <div>
      <h1>My first Formium form</h1>
      <FormiumForm
        data={form}
        onSubmit={async (values) => {
          await formium.submitForm('your_form_slug', values);
          setSuccess(true);
        }}
      />
    </div>
  );
}

Use your own React components

Now that you have everything setup and the data flowing, head over to the @formium/react docs to learn how to use your own React components with <FormiumForm> instead of the default ones.