Next.js & Formik: A Beginner’s Guide to Form Handling

Written by

learnmodernjavascript

in

Forms are a fundamental part of almost every web application. They allow users to input data, interact with your application, and ultimately, get things done. Building and managing forms, however, can quickly become complex, especially when dealing with validation, error handling, and state management. This is where Formik comes in. Formik is a popular and powerful library designed to simplify form handling in React and, by extension, Next.js. This tutorial will guide you through the process of integrating Formik into your Next.js projects, making form creation and management a breeze.

Why Formik? The Problem Formik Solves

Without a dedicated library, building forms in React can involve a lot of boilerplate code. You need to manage the form’s state, handle input changes, validate the data, and display error messages. This can lead to messy and repetitive code, making your application harder to maintain and debug. Formik addresses these pain points by providing a streamlined and declarative approach to form management. It handles state management, validation, submission, and error handling, allowing you to focus on the core logic of your forms.

What We’ll Cover

In this tutorial, we will:

  • Set up a basic Next.js project.
  • Install and configure Formik.
  • Create a simple form with input fields.
  • Implement basic validation using Formik and Yup (a validation library).
  • Handle form submission and display results.
  • Explore common Formik features and best practices.

Prerequisites

Before you start, make sure you have the following:

  • Node.js and npm (or yarn) installed on your system.
  • A basic understanding of React and Next.js concepts.
  • A code editor (like VS Code) installed.

Setting Up Your Next.js Project

If you don’t have a Next.js project set up already, let’s create one. Open your terminal and run the following command:

npx create-next-app formik-tutorial
cd formik-tutorial

This will create a new Next.js project named “formik-tutorial”. Navigate into the project directory using the cd command.

Installing Formik and Yup

Next, install Formik and Yup. Yup is a popular schema-based validation library that works seamlessly with Formik. In your terminal, run:

npm install formik yup

or if you use yarn:

yarn add formik yup

Creating a Simple Form

Let’s create a simple form with fields for name, email, and a message. Open the pages/index.js file (or your preferred page file) and replace its contents with the following code:

import { useFormik } from 'formik';
import * as Yup from 'yup';

function MyForm() {
  const formik = useFormik({
    initialValues: {
      name: '',
      email: '',
      message: '',
    },
    validationSchema: Yup.object({
      name: Yup.string().required('Required'),
      email: Yup.string().email('Invalid email address').required('Required'),
      message: Yup.string().required('Required'),
    }),
    onSubmit: async (values) => {
      // Simulate an API call
      await new Promise((r) => setTimeout(r, 500));
      alert(JSON.stringify(values, null, 2));
    },
  });

  return (
    <form onSubmit={formik.handleSubmit}>
      <div>
        <label htmlFor="name">Name</label>
        <input
          type="text"
          id="name"
          name="name"
          onChange={formik.handleChange}
          onBlur={formik.handleBlur}
          value={formik.values.name}
        />
        {formik.touched.name && formik.errors.name ? (
          <div className="error">{formik.errors.name}</div>
        ) : null}
      </div>

      <div>
        <label htmlFor="email">Email Address</label>
        <input
          type="email"
          id="email"
          name="email"
          onChange={formik.handleChange}
          onBlur={formik.handleBlur}
          value={formik.values.email}
        />
        {formik.touched.email && formik.errors.email ? (
          <div className="error">{formik.errors.email}</div>
        ) : null}
      </div>

      <div>
        <label htmlFor="message">Message</label>
        <textarea
          id="message"
          name="message"
          onChange={formik.handleChange}
          onBlur={formik.handleBlur}
          value={formik.values.message}
        />
        {formik.touched.message && formik.errors.message ? (
          <div className="error">{formik.errors.message}</div>
        ) : null}
      </div>

      <button type="submit" disabled={formik.isSubmitting}>
        Submit
      </button>
    </form>
  );
}

export default function Home() {
  return (
    <div>
      <h2>Formik Example</h2>
      <MyForm />
    </div>
  );
}

Let’s break down this code:

  • We import useFormik from ‘formik’ and Yup for validation.
  • Inside the MyForm component, we initialize Formik using the useFormik hook.
  • initialValues: This object sets the initial values for our form fields.
  • validationSchema: This is where we define our validation rules using Yup. We specify that the name, email, and message fields are required. The email field also uses Yup’s built-in email validation.
  • onSubmit: This function is called when the form is submitted. In this example, we simulate an API call with setTimeout and then display the form values in an alert. In a real application, you would make an API call here to submit the form data to your backend.
  • Inside the form, we have input fields for name, email, and message.
  • onChange, onBlur, and value are used to handle input changes, track the field has been blurred (touched), and display the current values, respectively.
  • We display error messages using formik.touched and formik.errors. formik.touched tells us if the field has been visited (blurred).
  • The submit button is disabled while the form is submitting (formik.isSubmitting).

To see the form, run your Next.js development server with npm run dev or yarn dev and navigate to http://localhost:3000 in your browser. You should see the form rendered on the page.

Adding Validation with Yup

The code above already includes basic validation using Yup. Let’s delve deeper into how Yup works. Yup allows you to define a schema for your form data, specifying the types, required fields, and other validation rules. This is done within the validationSchema property of the useFormik hook.

Here’s a breakdown of the Yup validation rules used in the example:

  • Yup.string(): Specifies that the field should be a string.
  • .required('Required'): Makes the field required and displays the error message “Required” if the field is empty.
  • .email('Invalid email address'): For the email field, this validates that the input is a valid email address, displaying the error message “Invalid email address” if it’s not.

You can extend these validation rules to cover various scenarios. For example, you can add rules for minimum and maximum lengths, regular expressions, and custom validation functions.

Here’s how you might add a minimum length requirement to the name field:

name: Yup.string().min(2, 'Must be at least 2 characters').required('Required'),

In this example, the name field must be at least 2 characters long. If it’s shorter, the error message “Must be at least 2 characters” will be displayed.

Handling Form Submission

The onSubmit function in Formik is where you handle the form submission. This is where you would typically make an API call to send the form data to your backend. In our example, we’re simulating an API call with setTimeout to demonstrate the asynchronous nature of a real-world submission.

Here’s a more detailed look at the onSubmit function:

onSubmit: async (values, { setSubmitting }) => {
  try {
    // Simulate an API call
    await new Promise((r) => setTimeout(r, 500));
    alert(JSON.stringify(values, null, 2));
    // Reset the form after successful submission (optional)
    // formik.resetForm();
  } catch (error) {
    // Handle errors (e.g., display an error message)
    console.error('Submission error:', error);
    // You might use formik.setErrors here if you get errors from the API
  } finally {
    // Always set submitting to false, even if there's an error
    setSubmitting(false);
  }
},

Key points:

  • values: This object contains the form data.
  • setSubmitting: This function is provided by Formik. It’s used to update the isSubmitting state, which we use to disable the submit button during the submission process.
  • Error Handling: The try...catch...finally block is essential for handling potential errors during the API call. If the API call fails, the catch block will execute, allowing you to handle the error gracefully (e.g., displaying an error message to the user).
  • finally block: Ensures that setSubmitting(false) is always called, regardless of whether the submission was successful or resulted in an error. This is important to re-enable the submit button.
  • Resetting the Form: After a successful submission, you can optionally reset the form using formik.resetForm().

Common Mistakes and How to Fix Them

Here are some common mistakes developers encounter when using Formik and how to fix them:

  1. Not Handling onBlur: Without handling the onBlur event on your input fields, validation errors might not appear until the user attempts to submit the form. The onBlur event triggers the validation when the input field loses focus.

    Fix: Make sure you include onBlur={formik.handleBlur} on each input field, as demonstrated in the example code.

  2. Incorrectly Accessing Errors: You might have trouble displaying the validation errors if you’re not accessing them correctly. Remember to use formik.errors.fieldName to access the error messages for each field.

    Fix: Double-check that you’re correctly referencing the error messages in your JSX. For example: {formik.touched.name && formik.errors.name ? ( <div className="error">{formik.errors.name}</div>) : null}

  3. Forgetting to Disable the Submit Button: During form submission, you should disable the submit button to prevent users from submitting the form multiple times. This is done using the formik.isSubmitting property.

    Fix: Add disabled={formik.isSubmitting} to your submit button.

  4. Incorrectly Handling Asynchronous Operations in onSubmit: If you’re making API calls in your onSubmit function, make sure you handle them correctly using async/await or Promises. Also, remember to set formik.setSubmitting(false) in the finally block to re-enable the submit button.

    Fix: Ensure your onSubmit function is async, and handle potential errors in a try...catch...finally block.

  5. Not Using touched Property: The formik.touched object indicates which fields have been visited by the user. Using this property, alongside formik.errors, prevents the error messages from appearing before the user interacts with the input field. Without this check, the error messages will appear immediately, even before the user has typed anything.

    Fix: Ensure you are using formik.touched to control when the error messages display: {formik.touched.name && formik.errors.name ? ( <div className="error">{formik.errors.name}</div>) : null}

Advanced Formik Features

Formik offers several advanced features to handle more complex scenarios:

  • Field Arrays: Formik supports field arrays, allowing you to manage dynamic lists of form fields. This is useful for creating forms with repeating sections, such as adding multiple items to a shopping cart.

    Example: <FieldArray name="items" component={MyItemComponent} />

  • Formik Context: You can access Formik’s context within your components using the useFormikContext hook. This is useful for accessing Formik’s state and methods from within nested components.

    Example: const formikContext = useFormikContext();

  • Custom Components: You can create custom components to handle specific form field types, such as date pickers or select boxes. This promotes reusability and keeps your form code organized.

    Example: <MyCustomInput fieldName="myField" />

  • Reusing Validation Schemas: If you have multiple forms with similar validation rules, you can reuse Yup validation schemas to avoid code duplication.

    Example: Create a separate file with a Yup schema and import it into your Formik component.

Key Takeaways and Best Practices

Here’s a summary of the key takeaways from this tutorial:

  • Formik simplifies form handling in Next.js by managing state, validation, and submission.
  • Yup provides a powerful and flexible way to define validation rules.
  • Use useFormik to initialize Formik and handle form logic.
  • Use initialValues to set the initial values of your form fields.
  • Use validationSchema to define your validation rules using Yup.
  • Use onSubmit to handle form submission.
  • Handle onChange, onBlur, and value to manage input field interactions.
  • Display error messages using formik.touched and formik.errors.
  • Disable the submit button during form submission using formik.isSubmitting.
  • Always handle errors in your onSubmit function.

Best practices to keep in mind:

  • Keep your forms modular and reusable.
  • Use clear and descriptive variable names.
  • Follow a consistent coding style.
  • Test your forms thoroughly.
  • Consider using a component library (like Material UI or Ant Design) to speed up form development.

FAQ

Here are some frequently asked questions about Formik:

  1. Can I use Formik without Yup?

    Yes, you can use Formik without Yup. However, Yup simplifies the process of defining and managing validation rules. You can also use custom validation functions with Formik.

  2. How do I handle file uploads with Formik?

    Formik can handle file uploads, but you’ll need to manage the file input’s state separately. You can use the onChange event to update the file in your formik values. Remember to handle file uploads server-side, as Formik is primarily a client-side library.

  3. How can I reset a form after submission?

    You can reset a form after submission by calling formik.resetForm() inside your onSubmit function after a successful API call.

  4. Does Formik support complex form layouts?

    Yes, Formik is flexible enough to handle complex form layouts. You can use CSS, component libraries, and custom components to create sophisticated forms.

  5. What are the alternatives to Formik?

    Popular alternatives to Formik include React Hook Form and Formik. Each library has its strengths and weaknesses, so choose the one that best suits your project’s needs.

Formik is a powerful and efficient tool for handling forms in your Next.js applications. By understanding the core concepts and best practices, you can create robust, user-friendly forms with ease. From setting up your project to implementing validation and handling submissions, Formik simplifies the entire process, allowing you to focus on building great user experiences. As you delve deeper into more complex features such as field arrays and custom components, you’ll discover even more ways to leverage Formik’s capabilities. With its declarative approach and ease of use, Formik will become an indispensable part of your toolkit for building web applications.

More posts