Mastering Next.js Forms: A Comprehensive Guide

Forms and data submission are crucial aspects of web applications. Next.js 13 introduces an innovative approach to handle form submissions and data mutations through Server Actions. In this three-part series, we will explore the power of Next.js 13's App Router in handling forms, form submissions, and error handling.

‍

How Server Actions Work

Next.js 13 introduces the concept of Server Actions, which simplifies form handling by allowing you to define asynchronous server functions directly within your components. Server Actions can be defined in both Server Components and Client Components, offering flexibility and progressive enhancement.

To enable Server Actions in your Next.js project, modify your next.config.js file as follows:

    module.exports = {
      experimental: {
        serverActions: true,
      },
    }

Here are some key points to understand about Server Actions:

Server Components: Forms calling Server Actions from Server Components can function without JavaScript.
Client Components: Forms calling Server Actions from Client Components will queue submissions if JavaScript isn't loaded yet, prioritizing client hydration.
Runtime Inheritance: Server Actions inherit the runtime from the page or layout they are used on.
Rendering Strategies: If a route uses a Server Action, it is required to render dynamically.

‍

Revalidating Cached Data

Server Actions in Next.js 13 integrate seamlessly with the caching and revalidation architecture. When a form is submitted, the Server Action can update cached data and trigger revalidation for relevant cache keys.

Unlike traditional applications that limit you to one form per route, Server Actions allow multiple actions per route. The browser doesn't need to refresh on form submission. Next.js can efficiently return both the updated UI and refreshed data in a single network roundtrip.

Let's delve deeper into these concepts with some practical examples.

‍

Server-only Forms

To create a server-only form, define the Server Action within a Server Component. You can define the action inline with the "use server" directive at the top of the function or in a separate file with the directive at the top of the file.

Here's a basic example:

    export default function Page() {
      async function create(formData: FormData) {
        'use server' // Mutate data and revalidate cache
      }
      
      return <form action={create}>...</form>
    }

In this example, we use the FormData data type, and the submitted data is accessible in the server action create.

Revalidating Data

Server Actions allow you to invalidate the Next.js Cache on demand. You can invalidate an entire route segment with revalidatePath:

    'use server';
    import { revalidatePath } from 'next/cache';
    
    export default async function submit() {
      await submitForm();
      revalidatePath('/');
    }

Or, you can invalidate a specific data fetch with a cache tag using revalidateTag:

‍

Redirecting

If you want to redirect the user to a different route after a Server Action is completed, you can use the redirect function along with an absolute or relative URL:

    'use server';
    import { redirect } from 'next/navigation';
    import { revalidateTag } from 'next/cache';
    
    export default async function submit() {
      const id = await addPost();
      revalidateTag('posts'); // Update cached posts
      redirect(`/post/${id}`); // Navigate to a new route
    }

‍

Form Validation

For basic form validation, HTML attributes like required and type="email" are recommended. However, for more advanced server-side validation, consider using a schema validation library like zod:

    import { z } from 'zod';
    
    const schema = z.object({
      // Define your validation rules here...
    });
    
    export default async function submit(formData: FormData) {
      const parsed = schema.parse({
        id: formData.get('id'),
        // Define the form data fields...
      });
      
      // Handle validation and data processing...
    }

‍

Displaying Loading State

You can utilize the useFormStatus hook to display a loading state while a form is submitting on the client side:

    'use client';
    import { experimental_useFormStatus as useFormStatus } from 'react-dom';
    
    function SubmitButton() {
      const { pending } = useFormStatus();
      
      return (
        <button disabled={pending}>
          {pending ? 'Submitting...' : 'Submit'}
        </button>
      );
    }

In this case, displaying loading or error states currently requires using Client Components. Future updates may provide server-side options for retrieving these values.

‍

Error Handling

Server Actions in Next.js 13 can handle errors gracefully. They are capable of returning serializable objects, making it easier to manage both success and error messages. Here's an example of how you can handle errors in a Server Action:

    'use server';
    
    export async function create(formData: FormData) {
      try {
        await createItem(formData.get('item'));
        revalidatePath('/');
        return { message: 'Success!' };
      } catch (e) {
        return { message: 'There was an error.' };
      }
    }

In this scenario, the create function attempts to create an item based on the form data. If an error occurs, it returns an error message; otherwise, it returns a success message.

From a Client Component, you can read this value and save it to the state, allowing the component to display the result of the Server Action to the user:

    'use client';
    import { create } from './actions';
    import { useState } from 'react';
    
    export default function Page() {
      const [message, setMessage] = useState<string>('');
      
      async function onCreate(formData: FormData) {
        const res = await create(formData);
        setMessage(res.message);
      }
      
      return (
        <form action={onCreate}>
          <input type="text" name="item" />
          <button type="submit">Add</button>
          <p>{message}</p>
        </form>
      );
    }

Remember that displaying loading or error states currently requires using Client Components, but Next.js is actively exploring options for server-side functions to retrieve these values.

‍

Optimistic Updates

Optimistic updates allow you to update the user interface optimistically before the Server Action finishes, rather than waiting for the response. This can provide a smoother user experience. Here's how you can implement optimistic updates in Next.js 13:

    'use client';
    import { experimental_useOptimistic as useOptimistic } from 'react';
    import { send } from './actions';

    type Message = {
      message: string;
    };

    export function Thread({ messages }: { messages: Message[] }) {
      const [optimisticMessages, addOptimisticMessage] = useOptimistic<Message[]>(
        messages,
        (state: Message[], newMessage: string) => [
          ...state,
          { message: newMessage },
        ]
      );

      return (
        <div>
          {optimisticMessages.map((m) => (
            <div>{m.message}</div>
          ))}
          <form
            action={async (formData: FormData) => {
              const message = formData.get('message');
              addOptimisticMessage(message);
              await send(message);
            }}
          >
            <input type="text" name="message" />
            <button type="submit">Send</button>
          </form>
        </div>
      );
    }

In this example, the UI is updated optimistically by adding the new message to the list of messages even before the send action is complete.

‍

Setting Cookies

Next.js 13's Server Actions also allow you to set cookies within the action using the cookies function:

    'use server';
    import { cookies } from 'next/headers';

    export async function create() {
      const cart = await createCart();
      cookies().set('cartId', cart.id);
    }

Here, after creating a cart, we set a cookie named 'cartId' with the cart's ID value.

‍

Reading Cookies

Reading cookies within a Server Action is straightforward using the cookies function:

    'use server';
    import { cookies } from 'next/headers';

    export async function read() {
      const auth = cookies().get('authorization')?.value;
      // ... Continue with your logic
    }

In this example, we retrieve the 'authorization' cookie value.

‍

Deleting Cookies

To delete cookies from within a Server Action, you can use the cookies function:

    'use server';
    import { cookies } from 'next/headers';

    export async function delete() {
      cookies().delete('name');
      // ... Continue with your logic
    }

Deleting cookies is essential for maintaining user privacy and security.

‍

Advanced Form Customization

Next.js 13's Server Actions provide flexibility for advanced form customization. You can extend this customization by modifying form behavior, layout, and appearance according to your application's requirements.

For instance, you can add advanced CSS styling, including properties like border-radius, font-family, and font-size to enhance the form's visual appeal:

<style jsx>{`
  form {
    display: flex;
    flex-direction: column;
    align-items: center;
  }
  input[type="text"] {
    border: 1px solid #ccc;
    border-radius: 4px;
    font-family: 'Arial', sans-serif;
    font-size: 16px;
    padding: 8px;
    margin: 4px;
  }
  button[type="submit"] {
    background-color: #0070f3;
    color: white;
    border: none;
    border-radius: 5px;
    font-family: 'Helvetica', sans-serif;
    font-size: 18px;
    padding: 10px 20px;
    margin-top: 16px;
    cursor: pointer;
  }
`}</style>

This CSS code snippet demonstrates how to apply styles to form elements such as text inputs and submit buttons. You can further customize styles to match your application's design.

‍

Handling Complex Data Structures

Next.js 13's Server Actions are not limited to simple forms with basic input fields. You can efficiently handle complex data structures, including objects and arrays, in your forms.

For example, suppose you have a form that collects data for creating a new user account, including personal information and preferences. You can structure your form and Server Action to handle this complex data:

    // Define the structure of user data
    const userSchema = z.object({
      firstName: z.string(),
      lastName: z.string(),
      email: z.string().email(),
      preferences: z.object({
        darkMode: z.boolean(),
        newsletter: z.boolean(),
      }),
    });

    // Server Action for creating a user
    export async function createUser(formData: FormData) {
      const userData = userSchema.parse({
        firstName: formData.get('firstName'),
        lastName: formData.get('lastName'),
        email: formData.get('email'),
        preferences: {
          darkMode: formData.get('darkMode') === 'on', // Convert checkbox value to a boolean
          newsletter: formData.get('newsletter') === 'on', // Convert checkbox value to a boolean
        },
      });

      // Process and save the user data
      // ...
    }

In this example, we use the zod library to define the structure of user data. The Server Action createUser extracts and validates form data, including complex preferences, before further processing.

‍

Enhancing User Experience

To enhance the user experience of your forms, you can incorporate features like client-side validation, real-time feedback, and dynamic form elements. Next.js 13's App Router provides the flexibility to implement these features seamlessly.

For instance, you can validate user inputs on the client side using JavaScript. Here's a simplified example of validating an email address:

    // Client-side email validation
    function isEmailValid(email) {
      const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
      return emailRegex.test(email);
    }

    export default function Page() {
      const [email, setEmail] = useState('');
      const [isValidEmail, setIsValidEmail] = useState(true);

      function handleEmailChange(event) {
        const newEmail = event.target.value;
        setEmail(newEmail);
        setIsValidEmail(isEmailValid(newEmail));
      }

      return (
        <form>
          <input
            type="email"
            value={email}
            onChange={handleEmailChange}
            className={isValidEmail ? '' : 'invalid'}
          />
          <button type="submit">Submit</button>
        </form>
      );
    }

‍

In this example, the handleEmailChange function checks if the entered email is valid and updates the component's state accordingly, allowing you to apply styling to indicate the input's validity.

Next.js Forms are a fundamental part of building interactive web applications. They enable users to input and submit data seamlessly. Whether it's a basic contact form on your website's contact page or a comprehensive multi-step data entry process, Next.js Forms provide the structure and tools you need.

In the world of web development, data is king. Form Data refers to the information users input into a form. This data could include anything from a user's name and email address to more complex structured data like preferences or survey responses.

Form Submission is the process of sending the form data from the user's browser to your server for processing. During this process, it's crucial to handle potential errors gracefully. Error Messages are messages displayed to the user when something goes wrong during form submission, such as incomplete fields or invalid data.

In scenarios where you expect a high volume of submissions, it's essential to ensure your form can handle multiple submissions simultaneously. Managing these Form Submissions efficiently can prevent performance bottlenecks.

A Contact Page is a common use case for forms on a website. In Next.js, you can create an API Route to handle form submissions from your Contact Page. API Routes are serverless functions that can handle various tasks, including processing form data.

When a user submits a form, the data is sent to the server, and the server responds with a result. The submit action initiates this process. Once the server processes the data, it sends back a response that can include success or error messages.

API Keys are essential for securing your API routes. They serve as access tokens that verify the authenticity of incoming requests. Keeping your API Keys secure is crucial to protect your application from unauthorized access.

React is a popular JavaScript library for building user interfaces. Importing React into your project allows you to create reusable components, including form elements and UI elements.

API Routes provide the backbone for handling form submissions. These routes define the endpoints where data is sent and processed. You can create, configure, and secure API Routes for various aspects of your application.

The Form Endpoint is the specific URL where your form data is sent for processing. You can customize this endpoint to match your application's routing structure and naming conventions.

Label Input Fields appropriately to provide clear instructions to users. Labels improve the accessibility and usability of your forms. Proper use of the htmlFor attribute ensures that screen readers and assistive technologies can interpret the labels correctly.

Display Error Messages in a user-friendly manner to guide users when they make mistakes in their submissions. Well-crafted error messages help users understand and correct their errors efficiently.

Just as important as handling errors is communicating success. Success Messages let users know that their submissions were successful, reinforcing a positive user experience.

When designing a Contact Form, consider the user experience. A well-crafted Contact Form should be intuitive, easy to use, and guide users through the process of reaching out to you.

Environment Variables provide a secure way to manage sensitive configuration data, such as API Keys and secrets. These variables can be accessed within your application to ensure secure communication.

To start building your Next.js application, you can create a new project using the create-next-app command. This command sets up the development environment and project structure.

A Development Server allows you to work on your application locally before deploying it to a production environment. It provides a controlled environment for testing and development.

Post Requests are HTTP requests used to submit form data to a server. When handling form submissions, you need to manage the Form State, keeping track of user interactions and data changes.

Handling Errors gracefully is crucial for maintaining a positive user experience. Errors can occur at various stages of form submission, from data validation to server processing.

In a Next.js application, you may encounter both Client-Side Errors, which occur in the user's browser, and Server-Side Errors, which occur on the server while processing form submissions. Both types of errors need to be handled effectively.

Components are building blocks of a Next.js application. You can create reusable components to structure your forms and UI elements. Exporting components allows you to use them across different parts of your application.

Styling plays a vital role in the overall look and feel of your application. You can define styles for various components, ensuring that your forms and UI elements are visually appealing and user-friendly.

We've taken a deep dive into forms in Next.js 13's App Router, exploring Server Actions, data handling, error management, form customization, and more. Next.js 13's Server Actions empower you to create dynamic, interactive forms that enhance the user experience while simplifying data processing and validation.

As you continue to work with Next.js 13's App Router, remember to adapt these concepts to your specific application's needs. The flexibility and power of Server Actions enable you to create forms that not only capture user input but also provide a delightful and engaging experience.

Thank you for joining us on this journey into the world of forms in Next.js 13. We hope you found this series informative and inspiring as you develop your web applications. If you have any questions or require further assistance, please feel free to reach out.

Happy coding, and may your forms be both functional and user-friendly!

Flutter

React

Android

iOS

Node.js

Plugin

Templates

Screen Library

About Us

Career

Contact Us

Documention

Discord

Blogs

Webflow

Airtable

Notion

Chargebee

Freshteam

Spotify

Slack

Google Sheets

Simplifying Next.js Forms Handling with Server Actions

Rakesh Purohit

Rakesh Purohit

How Server Actions Work

Revalidating Cached Data

Server-only Forms

Revalidating Data

Redirecting

Form Validation

Displaying Loading State

Error Handling

Optimistic Updates

Setting Cookies

Reading Cookies

Deleting Cookies

Advanced Form Customization

Handling Complex Data Structures

Enhancing User Experience

Frequently asked questions

Frequently asked questions

You’ve made it this far. Let’s build your first application

Products

Design to code

Learning

Comparison

Company

Double down for a greener Earth