Nextjs Using Form Libraries Like React Hook Form Complete Guide

Complete Examples, Step by Step for Beginners: Next.js with React Hook Form

Prerequisites

• Basic knowledge of JavaScript and React.
• Node.js and npm installed on your machine.

Step 1: Set Up Your Next.js Project

First, let's create a new Next.js project. Open your terminal and run:

npx create-next-app@latest nextjs-hook-form-example
cd nextjs-hook-form-example

Step 2: Install React Hook Form

Inside your Next.js project directory, install React Hook Form and its peer dependencies:

npm install react-hook-form @hookform/resolvers yup

In this example, we'll also use Yup for schema validation.

Step 3: Create a Simple Form Page

Now, let's create a new page for our form. In the pages directory, create a new file named form.js.

// pages/form.js

import React from 'react';
import { useForm } from 'react-hook-form';
import * as Yup from 'yup';
import { yupResolver } from '@hookform/resolvers/yup';

const schema = Yup.object().shape({
  name: Yup.string().required('Name is required').min(2, 'Name must be at least 2 characters'),
  email: Yup.string().email('Provide a valid email').required('Email is required'),
  age: Yup.number().positive('Age must be a positive number').integer('Age must be a whole number').required('Age is required').min(18, 'You must be at least 18 years old')
});

export default function MyForm() {
  const { register, handleSubmit, formState: { errors }, reset } = useForm({
    resolver: yupResolver(schema),
    defaultValues: {
      name: '',
      email: '',
      age: ''
    }
  });

  const onSubmit = async (data) => {
    // Example submission handler
    console.log(data);
    await fetch('/api/submit', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(data)
    }).then(() => {
      reset(); // Reset form after submission
    });
  };

  return (
    <div style={{ padding: '20px', maxWidth: '500px', margin: '0 auto' }}>
      <h1>Contact Form</h1>
      <form onSubmit={handleSubmit(onSubmit)}>
        <div>
          <label>Name:</label>
          <br />
          <input style={{ width: '100%', marginBottom: '10px' }} {...register('name')} placeholder="Enter your name" />
          <p style={{ color: 'red', fontSize: '14px' }}>{errors.name?.message}</p>
        </div>
        <div>
          <label>Email:</label>
          <br />
          <input style={{ width: '100%', marginBottom: '10px' }} {...register('email')} placeholder="Enter your email" />
          <p style={{ color: 'red', fontSize: '14px' }}>{errors.email?.message}</p>
        </div>
        <div>
          <label>Age:</label>
          <br />
          <input style={{ width: '100%', marginBottom: '10px' }} type="number" {...register('age')} placeholder="Enter your age" />
          <p style={{ color: 'red', fontSize: '14px' }}>{errors.age?.message}</p>
        </div>
        <button type="submit" style={{ padding: '10px 20px', backgroundColor: '#0070f3', color: '#fff', border: 'none', cursor: 'pointer' }}>Submit</button>
      </form>
    </div>
  );
}

In the above code:

• We import useForm from react-hook-form and yupResolver to integrate Yup validation.

• Define a Yup schema that enforces specific rules for each form field:

  • Name: Must be at least 2 characters long.
  • Email: Must be a valid email format.
  • Age: Must be a positive integer greater than or equal to 18.

• Use the register function from RHF to register each field with the hook.

• Use the handleSubmit function to attach our onSubmit handler when the form is submitted.

• Display corresponding error messages if the validation fails.

• Reset the form using the reset function once the form is successfully submitted.

Step 4: Create the API Endpoint

To handle the form submission on the server-side, let's create an API endpoint in Next.js. Inside the pages/api directory, create a new file named submit.js.

// pages/api/submit.js

export default function handler(req, res) {
  if (req.method === 'POST') {
    const { name, email, age } = req.body;

    // Here we would typically connect to a database or send data to a third-party service
    // For demonstration purposes, we're just logging it to the console and sending back a response
    console.log(`Name: ${name}, Email: ${email}, Age: ${age}`);

    res.status(200).json({ message: 'Form submitted successfully!' });
  } else {
    res.status(405).json({ message: 'Method not allowed' });
  }
}

This simple API handler logs the form data to the console when a POST request is made to /api/submit. In a real-world scenario, you would likely save this data to a database or perform other necessary actions.

Step 5: Create the Server-Side Validation

While RHF provides client-side validation using Yup, it's crucial to have server-side validation in place for security and reliability. We've already set up a basic server-side handler; now, let's enhance it by adding some form of validation on the server side. Although we're using Yup for client-side validation, the server-side logic will validate the presence and types of fields to ensure data integrity.

// pages/api/submit.js

const schema = require('../../schema'); // Import Yup schema
const { validateSync } = require('yup');

export default function handler(req, res) {
  if (req.method === 'POST') {
    try {
      // Validate with Yup schema
      validateSync(req.body, { abortEarly: false }); 

      // If validation passes, log the data and send success response
      const { name, email, age } = req.body;
      console.log(`Name: ${name}, Email: ${email}, Age: ${age}`);

      res.status(200).json({ message: 'Form submitted successfully!' });
      
    } catch (errors) {
      // Extract error messages and send as a bad request response
      const messages = errors.inner.map(err => err.message);
      res.status(400).json({ errors: messages });
    }
  } else {
    res.status(405).json({ message: 'Method not allowed' });
  }
}

Note: To make this code work, first export the Yup schema:

• Create a new file named schema.js in the root of your project and add the Yup schema:

// schema.js

const * as Yup from 'yup';

export default Yup.object().shape({
  name: Yup.string().required('Name is required').min(2, 'Name must be at least 2 characters'),
  email: Yup.string().email('Provide a valid email').required('Email is required'),
  age: Yup.number().positive('Age must be a positive number').integer('Age must be a whole number').required('Age is required').min(18, 'You must be at least 18 years old')
});

• Then update the form handler in pages/form.js to handle the potential errors from the server:

// pages/form.js

import React, { useState } from 'react';
import { useForm } from 'react-hook-form';
import * as Yup from 'yup';
import { yupResolver } from '@hookform/resolvers/yup';

const schema = Yup.object().shape({
  name: Yup.string().required('Name is required').min(2, 'Name must be at least 2 characters'),
  email: Yup.string().email('Provide a valid email').required('Email is required'),
  age: Yup.number().positive('Age must be a positive number').integer('Age must be a whole number').required('Age is required').min(18, 'You must be at least 18 years old')
});

export default function MyForm() {
  const [apiErrors, setApiErrors] = useState([]); // State variable to hold any server-side validation errors

  const { register, handleSubmit, formState: { errors }, reset } = useForm({
    resolver: yupResolver(schema),
    defaultValues: {
      name: '',
      email: '',
      age: ''
    }
  });

  const onSubmit = async (data) => {
    try {
      const response = await fetch('/api/submit', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(data)
      });

      if (response.ok) {
        // Handle successful submission
        console.log('Success!');
        reset();
        setApiErrors([]);

      } else if (response.status === 400) {
        // Handle validation errors returned from the server
        const result = await response.json(); 
        setApiErrors(result.errors);
        console.error('Validation Errors:', apiErrors);

      } else {
        // Handle other potential errors
        console.error('Error submitting form');
      }
      
    } catch(error) {
      console.error('Caught an error:', error);
    }
  };

  return (
    <div style={{ padding: '20px', maxWidth: '500px', margin: '0 auto' }}>
      <h1>Contact Form</h1>

      <form onSubmit={handleSubmit(onSubmit)}>
        <p style={{color: 'red', textAlign:'center'}}>{apiErrors.join(', ')}</p> {/* Display any server-side errors here */}
        
        <div>
          <label>Name:</label>
          <br />
          <input style={{ width: '100%', marginBottom: '10px' }} {...register('name')} placeholder="Enter your name" />
          <p style={{ color: 'red', fontSize: '14px' }}>{errors.name?.message}</p>
        </div>
        <div>
          <label>Email:</label>
          <br />
          <input style={{ width: '100%', marginBottom: '10px' }} {...register('email')} placeholder="Enter your email" />
          <p style={{ color: 'red', fontSize: '14px' }}>{errors.email?.message}</p>
        </div>
        <div>
          <label>Age:</label>
          <br />
          <input style={{ width: '100%', marginBottom: '10px' }} type="number" {...register('age')} placeholder="Enter your age" />
          <p style={{ color: 'red', fontSize: '14px' }}>{errors.age?.message}</p>
        </div>
        <button type="submit" style={{ padding: '10px 20px', backgroundColor: '#0070f3', color: '#fff', border: 'none', cursor: 'pointer' }}>Submit</button>
      </form>
    </div>
  );
}

Explanation:

• We introduced a new state variable apiErrors to manage and display server-side validation errors.
• Updated the onSubmit handler to:
  • Make a POST request to /api/submit.
  • Check if the response status is 200 (OK). If so, reset the form and clear any server-side errors.
  • If the status is 400 (Bad Request), extract the error messages from the JSON response and update apiErrors.
  • Otherwise, log the error and handle accordingly.

Step 6: Test the Form

Run your development server:

npm run dev

Navigate to http://localhost:3000/form in your web browser. You should see the contact form rendered there. Try entering different values, including those that don't meet the validation criteria, to see the client-side validation in action.

Upon submitting valid data, the form should reset, and in the console, you should see the submitted data logged by the API handler.

For invalid data, server-side validation errors (which match the client-side validation errors for simplicity) should be displayed just above the form.

Custom Styling and UX Improvements

To improve the styling and user experience, consider the following enhancements:

• CSS Modules/Styled Components: Apply custom styles using CSS modules or styled-components for better organization and encapsulation.

• Loading States: Add loading states to the form during submission to indicate that data is being processed.

• Success Messages: Once the form is submitted successfully, display a confirmation message to enhance user interaction.

• Custom Input Components: Encapsulate form fields into reusable components and manage their validation within these components for cleaner code organization.

Here's how you could extend the above example:

// pages/form.js

import React, { useState } from 'react';
import { useForm } from 'react-hook-form';
import * as Yup from 'yup';
import { yupResolver } from '@hookform/resolvers/yup';
import styles from './form.module.css'; // Import CSS module

const schema = Yup.object().shape({
  name: Yup.string().required('Name is required').min(2, 'Name must be at least 2 characters'),
  email: Yup.string().email('Provide a valid email').required('Email is required'),
  age: Yup.number().positive('Age must be a positive number').integer('Age must be a whole number').required('Age is required').min(18, 'You must be at least 18 years old')
});

export default function MyForm() {
  const [apiErrors, setApiErrors] = useState([]);
  const [isSubmitting, setIsSubmitting] = useState(false);
  const [successMessage, setSuccessMessage] = useState('');

  const { register, handleSubmit, formState: { errors }, reset } = useForm({
    resolver: yupResolver(schema),
    defaultValues: {
      name: '',
      email: '',
      age: ''
    }
  });

  const onSubmit = async (data) => {
    setIsSubmitting(true);
    setApiErrors([]);
    setSuccessMessage('');

    try {
      const response = await fetch('/api/submit', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(data)
      });

      if (response.ok) {
        const result = await response.json();
        setSuccessMessage(result.message);
        
        reset();
        setIsSubmitting(false);

      } else if (response.status === 400) {
        const result = await response.json(); 
        setApiErrors(result.errors);
        console.error('Validation Errors:', apiErrors);
        setIsSubmitting(false);
      
      } else {
        console.error('Error submitting form');
        setIsSubmitting(false);
      }

    } catch(error) {
      console.error('Caught an error:', error);
      setIsSubmitting(false);
    }
  };

  return (
    <div className={styles.container}>
      <h1>Contact Form</h1>

      <form onSubmit={handleSubmit(onSubmit)} className={styles.form}>
        <div>
          {apiErrors.length > 0 && (
            <div className={styles.apiError}>
              <p>{apiErrors.map((error, index) => <span key={index}>{error}</span>)}</p>
            </div>
          )}
          {successMessage && (
            <div className={styles.successMessage}>
              <p>{successMessage}</p>
            </div>
          )}
        </div>

        <div className={styles.fieldGroup}>
          <label htmlFor="name">Name:</label>
          <br />
          <input id="name" className={styles.input} {...register('name')} placeholder="Enter your name" />
          <p className={styles.error}>{errors.name?.message}</p>
        </div>
        <div className={styles.fieldGroup}>
          <label htmlFor="email">Email:</label>
          <br />
          <input id="email" className={styles.input} {...register('email')} placeholder="Enter your email" />
          <p className={styles.error}>{errors.email?.message}</p>
        </div>
        <div className={styles.fieldGroup}>
          <label htmlFor="age">Age:</label>
          <br />
          <input id="age" className={styles.input} type="number" {...register('age')} placeholder="Enter your age" />
          <p className={styles.error}>{errors.age?.message}</p>
        </div>
        <button type="submit" className={styles.button} disabled={isSubmitting}>
          {isSubmitting ? 'Submitting...' : 'Submit'}
        </button>
      </form>
    </div>
  );
}

// form.module.css

.container {
  padding: 20px;
  max-width: 500px;
  margin: 0 auto;
}

.form {
  display: flex;
  flex-direction: column;
}

.fieldGroup {
  margin-bottom: 10px;
}

.input {
  width: 100%;
  padding: 8px;
  box-sizing: border-box;
}

.error {
  color: red;
  font-size: 14px;
  margin-top: 5px;
}

.apiError, .successMessage {
  margin-bottom: 10px;
}

.apiError p, .successMessage p {
  padding: 8px;
  background-color: #fff3cd;
  border: 1px solid #ffec99;
  color: #856404;
  border-radius: 4px;
}

.successMessage p {
  background-color: #d4edda;
  border-color: #c3e6cb;
  color: #155724;
}

.button {
  padding: 10px 20px;
  background-color: #0070f3;
  color: white;
  border: none;
  cursor: pointer;
}

.button:disabled {
  background-color: #ccc;
  cursor: not-allowed;
}

With these changes, our form now includes:

• API Error Handling: Displays validation errors returned from the server.
• Success Messages: Shows confirmation text upon successful form submission.
• Loading Indicator: Changes button text to "Submitting..." while the form data is being sent.
• Improved Styling: Uses CSS modules for better styling organization.

You can now navigate to http://localhost:3000/form and see these improvements in action.

Conclusion

React Hook Form is a powerful tool for simplifying form management in React applications. In combination with Next.js for handling API requests and server-side validation, it offers robust form handling without compromising user experience.

By following this step-by-step example, you should have a foundational understanding of implementing forms with React Hook Form in a Next.js environment. Feel free to expand upon this example by integrating databases, third-party services, or additional form controls based on your needs. Happy coding!