Next.js course ยท Module 6: Forms and Server Actions

React Hook Form and Form State Management

19 min read ยท
In this lesson8

Forms are an integral part of most web applications, but effectively managing their state, validation, and error handling can be challenging. React Hook Form is one of the most popular libraries in the React ecosystem, designed to solve common form-related problems while maintaining high performance and low code complexity.

Why Use React Hook Form?

Before diving into implementation details, let's look at the main advantages of React Hook Form compared to native React solutions:

  1. Minimal rendering - the library minimizes unnecessary re-renders, resulting in better performance
  2. Less boilerplate code - compared to native controlled components
  3. Easy integration - works with both controlled and uncontrolled components
  4. Advanced validation - extensive validation capabilities, integration with Yup, Zod, Joi, and other libraries
  5. TypeScript typing - full TypeScript support
  6. Performance - optimized for performance, even in complex forms

React Hook Form Basics

Let's start with a simple login form example:

import { useForm, SubmitHandler } from 'react-hook-form';

type LoginInputs = {
  email: string;
  password: string;
  rememberMe: boolean;
};

export default function LoginForm() {
  const {
    register,
    handleSubmit,
    formState: { errors, isSubmitting }
  } = useForm<LoginInputs>();

  const onSubmit: SubmitHandler<LoginInputs> = async (data) => {
    // In a real application, we would call the API here
    console.log('Login data:', data);

    // Simulate network delay
    await new Promise(resolve => setTimeout(resolve, 1000));
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)} className="space-y-4">
      <div>
        <label htmlFor="email" className="block text-sm font-medium">
          Email
        </label>
        <input
          id="email"
          type="email"
          className={`mt-1 block w-full rounded-md ${errors.email ? 'border-red-500' : 'border-gray-300'}`}
          {...register('email', {
            required: 'Email is required',
            pattern: {
              value: /^\S+@\S+\.\S+$/,
              message: 'Invalid email format'
            }
          })}
        />
        {errors.email && (
          <p className="text-red-500 text-xs mt-1">{errors.email.message}</p>
        )}
      </div>

      <div>
        <label htmlFor="password" className="block text-sm font-medium">
          Password
        </label>
        <input
          id="password"
          type="password"
          className={`mt-1 block w-full rounded-md ${errors.password ? 'border-red-500' : 'border-gray-300'}`}
          {...register('password', {
            required: 'Password is required',
            minLength: {
              value: 6,
              message: 'Password must be at least 6 characters'
            }
          })}
        />
        {errors.password && (
          <p className="text-red-500 text-xs mt-1">{errors.password.message}</p>
        )}
      </div>

      <div className="flex items-center">
        <input
          id="rememberMe"
          type="checkbox"
          className="h-4 w-4 rounded border-gray-300"
          {...register('rememberMe')}
        />
        <label htmlFor="rememberMe" className="ml-2 block text-sm">
          Remember me
        </label>
      </div>

      <button
        type="submit"
        disabled={isSubmitting}
        className="w-full py-2 px-4 bg-blue-600 text-white rounded-md hover:bg-blue-700 disabled:opacity-50"
      >
        {isSubmitting ? 'Logging in...' : 'Log in'}
      </button>
    </form>
  );
}

The main React Hook Form elements in the above example:

  1. useForm - the main hook that provides methods for managing the form
  2. register - function that registers form fields in React Hook Form
  3. handleSubmit - function that wraps our form submission handler
  4. formState - object containing information about the form state, including errors and submission status

Advanced Validation with Zod

React Hook Form integrates excellently with validation libraries such as Zod, enabling the creation of robust validation schemas:

import { useForm, SubmitHandler } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';

// Schema definition with Zod
const signupSchema = z.object({
  username: z.string()
    .min(3, 'Username must be at least 3 characters')
    .max(20, 'Username can be at most 20 characters')
    .regex(/^[a-zA-Z0-9_]+$/, 'Username can only contain letters, digits, and underscores'),
  email: z.string()
    .email('Please provide a valid email address'),
  password: z.string()
    .min(8, 'Password must be at least 8 characters')
    .regex(/[A-Z]/, 'Password must contain at least one uppercase letter')
    .regex(/[a-z]/, 'Password must contain at least one lowercase letter')
    .regex(/[0-9]/, 'Password must contain at least one digit'),
  confirmPassword: z.string(),
  terms: z.boolean().refine(val => val === true, {
    message: 'You must accept the terms',
  }),
}).refine(data => data.password === data.confirmPassword, {
  message: 'Passwords do not match',
  path: ['confirmPassword'],
});

// Type resulting from the schema
type SignupInputs = z.infer<typeof signupSchema>;

export default function SignupForm() {
  const {
    register,
    handleSubmit,
    formState: { errors, isSubmitting, isSubmitSuccessful },
    reset
  } = useForm<SignupInputs>({
    resolver: zodResolver(signupSchema),
    defaultValues: {
      username: '',
      email: '',
      password: '',
      confirmPassword: '',
      terms: false
    }
  });

  const onSubmit: SubmitHandler<SignupInputs> = async (data) => {
    try {
      // Simulate sending data to API
      await new Promise(resolve => setTimeout(resolve, 1500));
      console.log('Registration data:', data);

      // Reset form after successful submission
      reset();
    } catch (error) {
      console.error('Registration error:', error);
    }
  };

  return (
    <div className="max-w-md mx-auto p-6 bg-white rounded-lg shadow-md">
      <h2 className="text-2xl font-bold mb-6">Registration</h2>

      {isSubmitSuccessful && (
        <div className="mb-4 p-3 bg-green-100 text-green-700 rounded">
          Registration completed successfully!
        </div>
      )}

      <form onSubmit={handleSubmit(onSubmit)} className="space-y-4">
        <div>
          <label htmlFor="username" className="block text-sm font-medium">
            Username
          </label>
          <input
            id="username"
            type="text"
            className={`mt-1 block w-full rounded-md ${errors.username ? 'border-red-500' : 'border-gray-300'}`}
            {...register('username')}
          />
          {errors.username && (
            <p className="text-red-500 text-xs mt-1">{errors.username.message}</p>
          )}
        </div>

        <div>
          <label htmlFor="email" className="block text-sm font-medium">
            Email
          </label>
          <input
            id="email"
            type="email"
            className={`mt-1 block w-full rounded-md ${errors.email ? 'border-red-500' : 'border-gray-300'}`}
            {...register('email')}
          />
          {errors.email && (
            <p className="text-red-500 text-xs mt-1">{errors.email.message}</p>
          )}
        </div>

        <div>
          <label htmlFor="password" className="block text-sm font-medium">
            Password
          </label>
          <input
            id="password"
            type="password"
            className={`mt-1 block w-full rounded-md ${errors.password ? 'border-red-500' : 'border-gray-300'}`}
            {...register('password')}
          />
          {errors.password && (
            <p className="text-red-500 text-xs mt-1">{errors.password.message}</p>
          )}
        </div>

        <div>
          <label htmlFor="confirmPassword" className="block text-sm font-medium">
            Confirm password
          </label>
          <input
            id="confirmPassword"
            type="password"
            className={`mt-1 block w-full rounded-md ${errors.confirmPassword ? 'border-red-500' : 'border-gray-300'}`}
            {...register('confirmPassword')}
          />
          {errors.confirmPassword && (
            <p className="text-red-500 text-xs mt-1">{errors.confirmPassword.message}</p>
          )}
        </div>

        <div className="flex items-center">
          <input
            id="terms"
            type="checkbox"
            className={`h-4 w-4 rounded ${errors.terms ? 'border-red-500' : 'border-gray-300'}`}
            {...register('terms')}
          />
          <label htmlFor="terms" className="ml-2 block text-sm">
            I accept the terms of service
          </label>
        </div>
        {errors.terms && (
          <p className="text-red-500 text-xs">{errors.terms.message}</p>
        )}

        <button
          type="submit"
          disabled={isSubmitting}
          className="w-full py-2 px-4 bg-blue-600 text-white rounded-md hover:bg-blue-700 disabled:opacity-50"
        >
          {isSubmitting ? 'Registering...' : 'Sign up'}
        </button>
      </form>
    </div>
  );
}

Key elements of this example:

  1. zodResolver - adapter that integrates Zod with React Hook Form
  2. Advanced validation rules - complex regular expressions, minimum length, etc.
  3. refine function - for custom validation conditions, such as comparing passwords
  4. z.infer<typeof schema> - automatic type generation from the schema definition

Dynamic Forms and Conditional Fields

React Hook Form handles dynamic forms excellently, in which fields can appear or disappear depending on conditions:

import { useForm, useWatch, SubmitHandler, Controller } from 'react-hook-form';
import { useState } from 'react';

type DeliveryMethod = 'standard' | 'express' | 'pickup';

type CheckoutInputs = {
  firstName: string;
  lastName: string;
  email: string;
  deliveryMethod: DeliveryMethod;
  address?: string;
  city?: string;
  postalCode?: string;
  pickupLocation?: string;
};

export default function DynamicCheckoutForm() {
  const {
    register,
    handleSubmit,
    control,
    formState: { errors, isSubmitting }
  } = useForm<CheckoutInputs>({
    defaultValues: {
      firstName: '',
      lastName: '',
      email: '',
      deliveryMethod: 'standard',
    }
  });

  // We use useWatch to observe changes in the selected delivery method
  const deliveryMethod = useWatch({
    control,
    name: 'deliveryMethod',
    defaultValue: 'standard',
  });

  // We check if we need a shipping address
  const needsShippingAddress = deliveryMethod === 'standard' || deliveryMethod === 'express';

  const onSubmit: SubmitHandler<CheckoutInputs> = async (data) => {
    // Simulate API delay
    await new Promise(resolve => setTimeout(resolve, 1000));
    console.log('Order data:', data);
  };

  return (
    <div className="max-w-md mx-auto p-6 bg-white rounded-lg shadow-md">
      <h2 className="text-2xl font-bold mb-6">Order Checkout</h2>

      <form onSubmit={handleSubmit(onSubmit)} className="space-y-6">
        <div className="grid grid-cols-2 gap-4">
          <div>
            <label htmlFor="firstName" className="block text-sm font-medium">
              First name
            </label>
            <input
              id="firstName"
              type="text"
              className={`mt-1 block w-full rounded-md ${errors.firstName ? 'border-red-500' : 'border-gray-300'}`}
              {...register('firstName', { required: 'Name is required' })}
            />
            {errors.firstName && (
              <p className="text-red-500 text-xs mt-1">{errors.firstName.message}</p>
            )}
          </div>

          <div>
            <label htmlFor="lastName" className="block text-sm font-medium">
              Last name
            </label>
            <input
              id="lastName"
              type="text"
              className={`mt-1 block w-full rounded-md ${errors.lastName ? 'border-red-500' : 'border-gray-300'}`}
              {...register('lastName', { required: 'Last name is required' })}
            />
            {errors.lastName && (
              <p className="text-red-500 text-xs mt-1">{errors.lastName.message}</p>
            )}
          </div>
        </div>

        <div>
          <label htmlFor="email" className="block text-sm font-medium">
            Email
          </label>
          <input
            id="email"
            type="email"
            className={`mt-1 block w-full rounded-md ${errors.email ? 'border-red-500' : 'border-gray-300'}`}
            {...register('email', {
              required: 'Email is required',
              pattern: {
                value: /^\S+@\S+\.\S+$/,
                message: 'Invalid email format'
              }
            })}
          />
          {errors.email && (
            <p className="text-red-500 text-xs mt-1">{errors.email.message}</p>
          )}
        </div>

        <div>
          <label className="block text-sm font-medium mb-2">
            Delivery method
          </label>

          <div className="space-y-2">
            <label className="flex items-center">
              <input
                type="radio"
                value="standard"
                className="mr-2"
                {...register('deliveryMethod')}
              />
              Standard delivery (2-3 business days)
            </label>

            <label className="flex items-center">
              <input
                type="radio"
                value="express"
                className="mr-2"
                {...register('deliveryMethod')}
              />
              Express delivery (24h)
            </label>

            <label className="flex items-center">
              <input
                type="radio"
                value="pickup"
                className="mr-2"
                {...register('deliveryMethod')}
              />
              Personal pickup
            </label>
          </div>
        </div>

        {needsShippingAddress && (
          <div className="space-y-4 p-4 bg-gray-50 rounded">
            <h3 className="font-medium">Shipping address</h3>

            <div>
              <label htmlFor="address" className="block text-sm font-medium">
                Address
              </label>
              <input
                id="address"
                type="text"
                className={`mt-1 block w-full rounded-md ${errors.address ? 'border-red-500' : 'border-gray-300'}`}
                {...register('address', { required: 'Address is required' })}
              />
              {errors.address && (
                <p className="text-red-500 text-xs mt-1">{errors.address.message}</p>
              )}
            </div>

            <div className="grid grid-cols-2 gap-4">
              <div>
                <label htmlFor="city" className="block text-sm font-medium">
                  City
                </label>
                <input
                  id="city"
                  type="text"
                  className={`mt-1 block w-full rounded-md ${errors.city ? 'border-red-500' : 'border-gray-300'}`}
                  {...register('city', { required: 'City is required' })}
                />
                {errors.city && (
                  <p className="text-red-500 text-xs mt-1">{errors.city.message}</p>
                )}
              </div>

              <div>
                <label htmlFor="postalCode" className="block text-sm font-medium">
                  Postal code
                </label>
                <input
                  id="postalCode"
                  type="text"
                  className={`mt-1 block w-full rounded-md ${errors.postalCode ? 'border-red-500' : 'border-gray-300'}`}
                  {...register('postalCode', {
                    required: 'Postal code is required',
                    pattern: {
                      value: /^\d{2}-\d{3}$/,
                      message: 'Format: 00-000'
                    }
                  })}
                />
                {errors.postalCode && (
                  <p className="text-red-500 text-xs mt-1">{errors.postalCode.message}</p>
                )}
              </div>
            </div>
          </div>
        )}

        {deliveryMethod === 'pickup' && (
          <div>
            <label htmlFor="pickupLocation" className="block text-sm font-medium">
              Pickup point
            </label>
            <select
              id="pickupLocation"
              className={`mt-1 block w-full rounded-md ${errors.pickupLocation ? 'border-red-500' : 'border-gray-300'}`}
              {...register('pickupLocation', { required: 'Select pickup point' })}
            >
              <option value="">Select pickup point</option>
              <option value="warszawa-centrum">Warsaw - Center</option>
              <option value="warszawa-mokotow">Warsaw - Mokotow</option>
              <option value="krakow-centrum">Krakow - Center</option>
              <option value="poznan-centrum">Poznan - Center</option>
            </select>
            {errors.pickupLocation && (
              <p className="text-red-500 text-xs mt-1">{errors.pickupLocation.message}</p>
            )}
          </div>
        )}

        <button
          type="submit"
          disabled={isSubmitting}
          className="w-full py-2 px-4 bg-blue-600 text-white rounded-md hover:bg-blue-700 disabled:opacity-50"
        >
          {isSubmitting ? 'Processing...' : 'Place order'}
        </button>
      </form>
    </div>
  );
}

Key elements of a dynamic form:

  1. useWatch - allows observing changes to selected form fields without triggering re-renders of the entire form
  2. Conditionally rendered sections - depending on the selected delivery method
  3. Conditional validation - different validation rules for different form sections

Multi-step Forms

React Hook Form also works great in multi-step forms:

import { useForm, SubmitHandler, FormProvider, useFormContext } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import { useState } from 'react';

// Personal data schema
const personalInfoSchema = z.object({
  firstName: z.string().min(1, 'Name is required'),
  lastName: z.string().min(1, 'Last name is required'),
  email: z.string().email('Invalid email format'),
  phoneNumber: z.string().regex(/^[0-9]{9}$/, 'Phone number must be 9 digits')
});

// Address schema
const addressSchema = z.object({
  street: z.string().min(1, 'Street is required'),
  city: z.string().min(1, 'City is required'),
  postalCode: z.string().regex(/^\d{2}-\d{3}$/, 'Postal code must be in 00-000 format'),
  country: z.string().min(1, 'Country is required')
});

// Payment schema
const paymentSchema = z.object({
  cardName: z.string().min(1, 'Name on card is required'),
  cardNumber: z.string().regex(/^[0-9]{16}$/, 'Card number must be 16 digits'),
  expiryDate: z.string().regex(/^(0[1-9]|1[0-2])\/[0-9]{2}$/, 'Format: MM/RR'),
  cvv: z.string().regex(/^[0-9]{3,4}$/, 'CVV must be 3 or 4 digits')
});

// Combined schema
const formSchema = z.object({
  personalInfo: personalInfoSchema,
  address: addressSchema,
  payment: paymentSchema
});

type MultiStepFormData = z.infer<typeof formSchema>;

// Personal data form step component
function PersonalInfoStep() {
  const { register, formState: { errors } } = useFormContext<MultiStepFormData>();

  return (
    <div className="space-y-4">
      <h2 className="text-xl font-bold">Personal data</h2>

      <div className="grid grid-cols-2 gap-4">
        <div>
          <label htmlFor="firstName" className="block text-sm font-medium">
            First name
          </label>
          <input
            id="firstName"
            type="text"
            className={`mt-1 block w-full rounded-md ${
              errors.personalInfo?.firstName ? 'border-red-500' : 'border-gray-300'
            }`}
            {...register('personalInfo.firstName')}
          />
          {errors.personalInfo?.firstName && (
            <p className="text-red-500 text-xs mt-1">{errors.personalInfo.firstName.message}</p>
          )}
        </div>

        <div>
          <label htmlFor="lastName" className="block text-sm font-medium">
            Last name
          </label>
          <input
            id="lastName"
            type="text"
            className={`mt-1 block w-full rounded-md ${
              errors.personalInfo?.lastName ? 'border-red-500' : 'border-gray-300'
            }`}
            {...register('personalInfo.lastName')}
          />
          {errors.personalInfo?.lastName && (
            <p className="text-red-500 text-xs mt-1">{errors.personalInfo.lastName.message}</p>
          )}
        </div>
      </div>

      <div>
        <label htmlFor="email" className="block text-sm font-medium">
          Email
        </label>
        <input
          id="email"
          type="email"
          className={`mt-1 block w-full rounded-md ${
            errors.personalInfo?.email ? 'border-red-500' : 'border-gray-300'
          }`}
          {...register('personalInfo.email')}
        />
        {errors.personalInfo?.email && (
          <p className="text-red-500 text-xs mt-1">{errors.personalInfo.email.message}</p>
        )}
      </div>

      <div>
        <label htmlFor="phoneNumber" className="block text-sm font-medium">
          Phone number
        </label>
        <input
          id="phoneNumber"
          type="tel"
          className={`mt-1 block w-full rounded-md ${
            errors.personalInfo?.phoneNumber ? 'border-red-500' : 'border-gray-300'
          }`}
          {...register('personalInfo.phoneNumber')}
        />
        {errors.personalInfo?.phoneNumber && (
          <p className="text-red-500 text-xs mt-1">{errors.personalInfo.phoneNumber.message}</p>
        )}
      </div>
    </div>
  );
}

// Address form step component
function AddressStep() {
  const { register, formState: { errors } } = useFormContext<MultiStepFormData>();

  return (
    <div className="space-y-4">
      <h2 className="text-xl font-bold">Shipping address</h2>

      <div>
        <label htmlFor="street" className="block text-sm font-medium">
          Street and number
        </label>
        <input
          id="street"
          type="text"
          className={`mt-1 block w-full rounded-md ${
            errors.address?.street ? 'border-red-500' : 'border-gray-300'
          }`}
          {...register('address.street')}
        />
        {errors.address?.street && (
          <p className="text-red-500 text-xs mt-1">{errors.address.street.message}</p>
        )}
      </div>

      <div className="grid grid-cols-2 gap-4">
        <div>
          <label htmlFor="city" className="block text-sm font-medium">
            City
          </label>
          <input
            id="city"
            type="text"
            className={`mt-1 block w-full rounded-md ${
              errors.address?.city ? 'border-red-500' : 'border-gray-300'
            }`}
            {...register('address.city')}
          />
          {errors.address?.city && (
            <p className="text-red-500 text-xs mt-1">{errors.address.city.message}</p>
          )}
        </div>

        <div>
          <label htmlFor="postalCode" className="block text-sm font-medium">
            Postal code
          </label>
          <input
            id="postalCode"
            type="text"
            className={`mt-1 block w-full rounded-md ${
              errors.address?.postalCode ? 'border-red-500' : 'border-gray-300'
            }`}
            {...register('address.postalCode')}
          />
          {errors.address?.postalCode && (
            <p className="text-red-500 text-xs mt-1">{errors.address.postalCode.message}</p>
          )}
        </div>
      </div>

      <div>
        <label htmlFor="country" className="block text-sm font-medium">
          Country
        </label>
        <select
          id="country"
          className={`mt-1 block w-full rounded-md ${
            errors.address?.country ? 'border-red-500' : 'border-gray-300'
          }`}
          {...register('address.country')}
        >
          <option value="">Select country</option>
          <option value="Poland">Poland</option>
          <option value="Germany">Germany</option>
          <option value="France">France</option>
          <option value="UK">United Kingdom</option>
        </select>
        {errors.address?.country && (
          <p className="text-red-500 text-xs mt-1">{errors.address.country.message}</p>
        )}
      </div>
    </div>
  );
}

// Payment form step component
function PaymentStep() {
  const { register, formState: { errors } } = useFormContext<MultiStepFormData>();

  return (
    <div className="space-y-4">
      <h2 className="text-xl font-bold">Payment method</h2>

      <div>
        <label htmlFor="cardName" className="block text-sm font-medium">
          Name on card
        </label>
        <input
          id="cardName"
          type="text"
          className={`mt-1 block w-full rounded-md ${
            errors.payment?.cardName ? 'border-red-500' : 'border-gray-300'
          }`}
          {...register('payment.cardName')}
        />
        {errors.payment?.cardName && (
          <p className="text-red-500 text-xs mt-1">{errors.payment.cardName.message}</p>
        )}
      </div>

      <div>
        <label htmlFor="cardNumber" className="block text-sm font-medium">
          Card number
        </label>
        <input
          id="cardNumber"
          type="text"
          className={`mt-1 block w-full rounded-md ${
            errors.payment?.cardNumber ? 'border-red-500' : 'border-gray-300'
          }`}
          {...register('payment.cardNumber')}
        />
        {errors.payment?.cardNumber && (
          <p className="text-red-500 text-xs mt-1">{errors.payment.cardNumber.message}</p>
        )}
      </div>

      <div className="grid grid-cols-2 gap-4">
        <div>
          <label htmlFor="expiryDate" className="block text-sm font-medium">
            Expiry date
          </label>
          <input
            id="expiryDate"
            type="text"
            className={`mt-1 block w-full rounded-md ${
              errors.payment?.expiryDate ? 'border-red-500' : 'border-gray-300'
            }`}
            {...register('payment.expiryDate')}
          />
          {errors.payment?.expiryDate && (
            <p className="text-red-500 text-xs mt-1">{errors.payment.expiryDate.message}</p>
          )}
        </div>

        <div>
          <label htmlFor="cvv" className="block text-sm font-medium">
            CVV
          </label>
          <input
            id="cvv"
            type="text"
            className={`mt-1 block w-full rounded-md ${
              errors.payment?.cvv ? 'border-red-500' : 'border-gray-300'
            }`}
            {...register('payment.cvv')}
          />
          {errors.payment?.cvv && (
            <p className="text-red-500 text-xs mt-1">{errors.payment.cvv.message}</p>
          )}
        </div>
      </div>
    </div>
  );
}

// Summary component
function SummaryStep({ data }: { data: MultiStepFormData }) {
  return (
    <div className="space-y-6">
      <h2 className="text-xl font-bold">Order summary</h2>

      <div className="bg-gray-50 p-4 rounded">
        <h3 className="font-medium mb-2">Personal data</h3>
        <p>{data.personalInfo.firstName} {data.personalInfo.lastName}</p>
        <p>{data.personalInfo.email}</p>
        <p>Phone: {data.personalInfo.phoneNumber}</p>
      </div>

      <div className="bg-gray-50 p-4 rounded">
        <h3 className="font-medium mb-2">Shipping address</h3>
        <p>{data.address.street}</p>
        <p>{data.address.postalCode} {data.address.city}</p>
        <p>{data.address.country}</p>
      </div>

      <div className="bg-gray-50 p-4 rounded">
        <h3 className="font-medium mb-2">Payment method</h3>
        <p>{data.payment.cardName}</p>
        <p>Card: **** **** **** {data.payment.cardNumber.slice(-4)}</p>
        <p>Valid until: {data.payment.expiryDate}</p>
      </div>
    </div>
  );
}

export default function MultiStepForm() {
  const [currentStep, setCurrentStep] = useState(0);
  const [isSubmitted, setIsSubmitted] = useState(false);

  const methods = useForm<MultiStepFormData>({
    resolver: zodResolver(formSchema),
    mode: 'onBlur',
    defaultValues: {
      personalInfo: {
        firstName: '',
        lastName: '',
        email: '',
        phoneNumber: ''
      },
      address: {
        street: '',
        city: '',
        postalCode: '',
        country: ''
      },
      payment: {
        cardName: '',
        cardNumber: '',
        expiryDate: '',
        cvv: ''
      }
    }
  });

  const steps = [
    { name: 'Personal data', component: <PersonalInfoStep /> },
    { name: 'Address', component: <AddressStep /> },
    { name: 'Payment', component: <PaymentStep /> },
    { name: 'Summary', component: <SummaryStep data={methods.getValues()} /> }
  ];

  const onSubmit: SubmitHandler<MultiStepFormData> = async (data) => {
    // Final data submission processing
    if (currentStep === steps.length - 1) {
      await new Promise(resolve => setTimeout(resolve, 1500));
      console.log('Order placed:', data);
      setIsSubmitted(true);
    } else {
      // Move to the next step
      setCurrentStep(prev => prev + 1);
    }
  };

  const handlePrevStep = () => {
    setCurrentStep(prev => Math.max(0, prev - 1));
  };

  const validateCurrentStep = async () => {
    let isValid = false;

    switch (currentStep) {
      case 0:
        isValid = await methods.trigger('personalInfo');
        break;
      case 1:
        isValid = await methods.trigger('address');
        break;
      case 2:
        isValid = await methods.trigger('payment');
        break;
      case 3:
        isValid = true; // Summary doesn't require validation
        break;
    }

    return isValid;
  };

  const handleNextStep = async () => {
    const isValid = await validateCurrentStep();

    if (isValid) {
      setCurrentStep(prev => Math.min(steps.length - 1, prev + 1));
    }
  };

  return (
    <div className="max-w-2xl mx-auto p-6 bg-white rounded-lg shadow-md">
      {isSubmitted ? (
        <div className="text-center py-8">
          <svg className="w-16 h-16 text-green-500 mx-auto mb-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M5 13l4 4L19 7" />
          </svg>
          <h2 className="text-2xl font-bold mb-2">Order accepted!</h2>
          <p className="text-gray-600 mb-4">Thank you for placing your order. We have sent the details to the provided email address.</p>
          <button
            onClick={() => {
              methods.reset();
              setCurrentStep(0);
              setIsSubmitted(false);
            }}
            className="px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700"
          >
            Place new order
          </button>
        </div>
      ) : (
        <>
          {/* Progress bar */}
          <div className="mb-8">
            <div className="flex justify-between mb-2">
              {steps.map((step, index) => (
                <div key={index} className="flex flex-col items-center">
                  <div
                    className={`w-8 h-8 flex items-center justify-center rounded-full ${index <= currentStep ? 'bg-blue-600 text-white' : 'bg-gray-200 text-gray-600'}`}
                  >
                    {index + 1}
                  </div>
                  <span className="text-xs mt-1">{step.name}</span>
                </div>
              ))}
            </div>
            <div className="relative w-full h-2 bg-gray-200 rounded-full overflow-hidden">
              <div
                className="absolute h-full bg-blue-600 transition-all duration-300"
                style={{ width: `${(currentStep / (steps.length - 1)) * 100}%` }}
              ></div>
            </div>
          </div>

          <FormProvider {...methods}>
            <form onSubmit={methods.handleSubmit(onSubmit)} className="space-y-8">
              {steps[currentStep].component}

              <div className="flex justify-between mt-8">
                <button
                  type="button"
                  onClick={handlePrevStep}
                  disabled={currentStep === 0}
                  className="px-4 py-2 border border-gray-300 rounded-md hover:bg-gray-50 disabled:opacity-50"
                >
                  Back
                </button>

                {currentStep < steps.length - 1 ? (
                  <button
                    type="button"
                    onClick={handleNextStep}
                    className="px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700"
                  >
                    Next
                  </button>
                ) : (
                  <button
                    type="submit"
                    className="px-4 py-2 bg-green-600 text-white rounded-md hover:bg-green-700"
                  >
                    {methods.formState.isSubmitting ? 'Processing...' : 'Place order'}
                  </button>
                )}
              </div>
            </form>
          </FormProvider>
        </>
      )}
    </div>
  );
}

Main elements of a multi-step form:

  1. FormProvider - provides form context for nested components
  2. useFormContext - allows child components to access form methods
  3. Nested fields - using dot notation (e.g. personalInfo.firstName)
  4. Step-by-step validation - using the trigger method to validate specific parts of the form

Integration with Server Actions in Next.js

React Hook Form can easily be combined with Server Actions in Next.js:

// app/newsletter/page.tsx
'use client';

import { useForm, SubmitHandler } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import { useState } from 'react';
import { subscribeToNewsletter } from './actions';

const newsletterSchema = z.object({
  email: z.string().email('Please provide a valid email address'),
  firstName: z.string().min(1, 'Name is required'),
  preferences: z.object({
    marketing: z.boolean().optional(),
    updates: z.boolean().optional(),
    news: z.boolean().optional()
  }).refine(prefs => prefs.marketing || prefs.updates || prefs.news, {
    message: 'Select at least one preference',
    path: ['_errors']
  })
});

type NewsletterFormInputs = z.infer<typeof newsletterSchema>;

export default function NewsletterForm() {
  const [submitStatus, setSubmitStatus] = useState<{ success: boolean; message: string } | null>(null);

  const {
    register,
    handleSubmit,
    formState: { errors, isSubmitting },
    reset
  } = useForm<NewsletterFormInputs>({
    resolver: zodResolver(newsletterSchema),
    defaultValues: {
      email: '',
      firstName: '',
      preferences: {
        marketing: false,
        updates: false,
        news: false
      }
    }
  });

  const onSubmit: SubmitHandler<NewsletterFormInputs> = async (data) => {
    try {
      // Call Server Action
      const result = await subscribeToNewsletter(data);

      setSubmitStatus({
        success: result.success,
        message: result.message
      });

      if (result.success) {
        reset(); // Reset form after successful submission
      }
    } catch (error) {
      setSubmitStatus({
        success: false,
        message: 'An unexpected error occurred. Please try again later.'
      });
    }
  };

  return (
    <div className="max-w-md mx-auto p-6 bg-white rounded-lg shadow-md">
      <h2 className="text-2xl font-bold mb-6">Subscribe to newsletter</h2>

      {submitStatus && (
        <div className={`mb-4 p-3 rounded ${submitStatus.success ? 'bg-green-100 text-green-700' : 'bg-red-100 text-red-700'}`}>
          {submitStatus.message}
        </div>
      )}

      <form onSubmit={handleSubmit(onSubmit)} className="space-y-4">
        <div>
          <label htmlFor="email" className="block text-sm font-medium">
            Email
          </label>
          <input
            id="email"
            type="email"
            className={`mt-1 block w-full rounded-md ${errors.email ? 'border-red-500' : 'border-gray-300'}`}
            {...register('email')}
          />
          {errors.email && (
            <p className="text-red-500 text-xs mt-1">{errors.email.message}</p>
          )}
        </div>

        <div>
          <label htmlFor="firstName" className="block text-sm font-medium">
            First name
          </label>
          <input
            id="firstName"
            type="text"
            className={`mt-1 block w-full rounded-md ${errors.firstName ? 'border-red-500' : 'border-gray-300'}`}
            {...register('firstName')}
          />
          {errors.firstName && (
            <p className="text-red-500 text-xs mt-1">{errors.firstName.message}</p>
          )}
        </div>

        <div>
          <label className="block text-sm font-medium mb-2">
            Newsletter preferences
          </label>

          <div className="space-y-2">
            <label className="flex items-center">
              <input
                type="checkbox"
                className="h-4 w-4 rounded border-gray-300 mr-2"
                {...register('preferences.marketing')}
              />
              Marketing information and promotions
            </label>

            <label className="flex items-center">
              <input
                type="checkbox"
                className="h-4 w-4 rounded border-gray-300 mr-2"
                {...register('preferences.updates')}
              />
              Product and service updates
            </label>

            <label className="flex items-center">
              <input
                type="checkbox"
                className="h-4 w-4 rounded border-gray-300 mr-2"
                {...register('preferences.news')}
              />
              Industry news
            </label>
          </div>

          {errors.preferences?.['_errors'] && (
            <p className="text-red-500 text-xs mt-1">{errors.preferences['_errors'].join(', ')}</p>
          )}
        </div>

        <button
          type="submit"
          disabled={isSubmitting}
          className="w-full py-2 px-4 bg-blue-600 text-white rounded-md hover:bg-blue-700 disabled:opacity-50"
        >
          {isSubmitting ? 'Sending...' : 'Subscribe'}
        </button>
      </form>
    </div>
  );
}

And the Server Action file:

// app/newsletter/actions.ts
'use server';

import { z } from 'zod';

const newsletterSchema = z.object({
  email: z.string().email(),
  firstName: z.string().min(1),
  preferences: z.object({
    marketing: z.boolean().optional(),
    updates: z.boolean().optional(),
    news: z.boolean().optional()
  })
});

type NewsletterData = z.infer<typeof newsletterSchema>;

export async function subscribeToNewsletter(data: NewsletterData) {
  // Validate data on the server for security
  const validationResult = newsletterSchema.safeParse(data);

  if (!validationResult.success) {
    return {
      success: false,
      message: 'Invalid data. Check the form and try again.'
    };
  }

  try {
    // Simulate API delay
    await new Promise(resolve => setTimeout(resolve, 1000));

    // Here would be the actual code to subscribe the user to the newsletter
    // e.g. API call, save to database etc.
    console.log('Subscribed to newsletter:', validationResult.data);

    return {
      success: true,
      message: 'Thank you for subscribing to the newsletter!'
    };
  } catch (error) {
    console.error('Error while subscribing to newsletter:', error);
    return {
      success: false,
      message: 'An error occurred during processing. Please try again later.'
    };
  }
}

Main elements of integrating React Hook Form with Server Actions:

  1. Shared typing - the same data type is used on both client and server side
  2. Two-way validation - data is validated both by React Hook Form and on the server
  3. Error handling - comprehensive error handling on both sides

Best Practices and Tips

  1. Use TypeScript - it provides static typing and enables compile-time error detection

  2. Split components - divide large forms into smaller, manageable components

  3. Use mode: 'onBlur' - validate forms when leaving a field rather than on every change:

    const { register } = useForm({ mode: 'onBlur' });
  4. Use shouldUnregister - for dynamic form fields that may appear and disappear:

    const { register } = useForm({ shouldUnregister: true });
  5. Use setValue for complex cases - for programmatically setting values:

    setValue('field', value, { shouldValidate: true, shouldDirty: true });
  6. Use transform for formatting data:

    register('amount', {
      setValueAs: value => parseFloat(value) || 0
    });

Summary

React Hook Form is a powerful tool that significantly simplifies creating and managing forms in React. Main advantages:

  • Performance - minimal component re-renders
  • Less code - less boilerplate compared to native controlled components
  • Flexibility - works with both controlled and uncontrolled components
  • Advanced validation - especially combined with libraries like Zod or Yup
  • TypeScript - full typing support

By connecting React Hook Form with Server Actions in Next.js, you can build efficient, secure, and user-friendly forms that behave well both with JavaScript enabled and disabled (thanks to progressive enhancement in Next.js).

Proper form management is crucial for building high-quality web applications, and React Hook Form makes this process significantly simpler and more enjoyable for both developers and end users.

Code for this lesson: App.tsx
import React, { useState } from 'react';

// Simulation React Hook Form - useForm, register, handleSubmit
// (without an external library, so it works in sandpack)

type FormValues = { username: string; email: string; age: string; bio: string };
type Errors = Partial<Record<keyof FormValues, string>>;

// Simplified useForm implementation
function useForm() {
  const [values, setValues] = useState<FormValues>({ username: '', email: '', age: '', bio: '' });
  const [errors, setErrors] = useState<Errors>({});
  const [touched, setTouched] = useState<Set<string>>(new Set());

  const register = (name: keyof FormValues) => ({
    value: values[name],
    onChange: (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => {
      setValues(prev => ({ ...prev, [name]: e.target.value }));
      if (touched.has(name)) validate({ ...values, [name]: e.target.value });
    },
    onBlur: () => {
      setTouched(prev => new Set(prev).add(name));
      validate(values);
    },
  });

  const validate = (vals: FormValues): boolean => {
    const errs: Errors = {};
    if (!vals.username) errs.username = 'Username is required';
    if (!vals.email) errs.email = 'Email is required';
    else if (!/\S+@\S+\.\S+/.test(vals.email)) errs.email = 'Invalid email format';
    if (vals.age && (isNaN(Number(vals.age)) || Number(vals.age) < 1)) errs.age = 'Enter a valid age';
    setErrors(errs);
    return Object.keys(errs).length === 0;
  };

  const handleSubmit = (onValid: (data: FormValues) => void) => (e: React.FormEvent) => {
    e.preventDefault();
    setTouched(new Set(Object.keys(values)));
    if (validate(values)) onValid(values);
  };

  return { register, handleSubmit, errors, values };
}

export default function ReactHookFormDemo() {
  const { register, handleSubmit, errors, values } = useForm();
  const [submitted, setSubmitted] = useState<FormValues | null>(null);

  const onSubmit = (data: FormValues) => setSubmitted(data);

  const inputStyle: React.CSSProperties = {
    width: '100%', padding: '10px', background: '#0d1117',
    border: '1px solid #333', borderRadius: 6, color: '#e0e0e0',
    fontFamily: 'monospace', fontSize: 13, boxSizing: 'border-box'
  };

  const errorStyle: React.CSSProperties = { color: '#f44336', fontSize: 11, marginTop: 4 };

  return (
    <div style={{ background: '#0f0f23', minHeight: '100vh', padding: 20, color: '#e0e0e0', fontFamily: 'monospace' }}>
      <h1 style={{ color: '#64ffda' }}>React Hook Form</h1>
      <p style={{ color: '#888', fontSize: 13, marginBottom: 16 }}>
        useForm + register + handleSubmit - minimal re-renders, easy validation.
      </p>

      <form onSubmit={handleSubmit(onSubmit)} style={{ maxWidth: 400 }}>
        <div style={{ marginBottom: 12 }}>
          <label style={{ color: '#64ffda', fontSize: 12, display: 'block', marginBottom: 4 }}>
            Username * <code style={{ color: '#555' }}>...register('username')</code>
          </label>
          <input {...register('username')} style={{ ...inputStyle, borderColor: errors.username ? '#f44336' : '#333' }} />
          {errors.username && <div style={errorStyle}>{errors.username}</div>}
        </div>

        <div style={{ marginBottom: 12 }}>
          <label style={{ color: '#64ffda', fontSize: 12, display: 'block', marginBottom: 4 }}>
            Email * <code style={{ color: '#555' }}>...register('email')</code>
          </label>
          <input {...register('email')} style={{ ...inputStyle, borderColor: errors.email ? '#f44336' : '#333' }} />
          {errors.email && <div style={errorStyle}>{errors.email}</div>}
        </div>

        <div style={{ marginBottom: 12 }}>
          <label style={{ color: '#64ffda', fontSize: 12, display: 'block', marginBottom: 4 }}>Age</label>
          <input {...register('age')} style={{ ...inputStyle, borderColor: errors.age ? '#f44336' : '#333' }} />
          {errors.age && <div style={errorStyle}>{errors.age}</div>}
        </div>

        <div style={{ marginBottom: 12 }}>
          <label style={{ color: '#64ffda', fontSize: 12, display: 'block', marginBottom: 4 }}>Bio</label>
          <textarea {...register('bio')} rows={2} style={{ ...inputStyle, resize: 'vertical' }} />
        </div>

        <button type="submit" style={{
          background: '#9c27b0', color: '#fff', border: 'none', borderRadius: 6,
          padding: '10px 20px', cursor: 'pointer', fontFamily: 'monospace', width: '100%'
        }}>
          handleSubmit(onSubmit)
        </button>
      </form>

      {submitted && (
        <div style={{ marginTop: 16, background: '#1b5e20', borderRadius: 8, padding: 12, maxWidth: 400, border: '1px solid #4caf50' }}>
          <div style={{ color: '#4caf50', marginBottom: 4 }}>Data validated and sent!</div>
          <pre style={{ color: '#ccc', fontSize: 11, margin: 0 }}>{JSON.stringify(submitted, null, 2)}</pre>
        </div>
      )}
    </div>
  );
}

Docs entries used in this lesson

Spotted a mistake in this lesson?

Check yourself

Answer the questions from this lesson. Pick an answer to see right away whether it is correct.

  1. 1. React Hook Form is:

Hands-on tasks in the game

  • Code editor

    Build an interface with interactive forms

  • Horizontal ordering

    Arrange the syntax of a form element with onSubmit in React

  • Click in order

    Arrange the elements in the correct order: const โ†’ { โ†’ register,

  • Code editor

    Create a login form with email and password field validation

  1. QuestionReact Hook Form is:
  2. Coding taskPractice: Interactive Forms
  3. Put in orderForm syntax with onSubmit in React
  4. Click in orderSequence: const โ†’ { โ†’ register,
  5. Coding taskPractice: Login Form with Validation

Useful articles