How do I handle Zod validation errors with useActionState in Next.js 15?

[devMosaic]

I am upgrading to Next.js 15 (React 19 RC) and I see that useFormState is being replaced by useActionState.
I want to validate a simple "Subscribe" form using Zod inside a Server Action and return specific error messages (e.g., "Invalid email") to the UI.

Previously I just returned an object, but I'm confused about the initial state and type safety with the new hook. Does anyone have a clean pattern for this?

[Arjun-M]

Hi there! 👋

This is a great question! The transition from useFormState to useActionState is one of the most common friction points in the Next.js 15 upgrade, but the new API is actually cleaner once you get the boilerplate down.

Here is a robust pattern using Zod for validation and TypeScript for type-safe error handling.

Step 1: Define your State Type & Action

First, create your action. Note that we return a State object that includes both errors and a message.

// actions.ts
'use server'

import { z } from 'zod'

// 1. Define the Zod Schema
const subscribeSchema = z.object({
  email: z.string().email({ message: "Please enter a valid email address." }),
})

// 2. Define the State interface
export type FormState = {
  errors?: {
    email?: string[]
  }
  message?: string | null
}

// 3. Create the Server Action
export async function subscribe(prevState: FormState, formData: FormData): Promise<FormState> {
  // Extract data
  const email = formData.get('email')

  // Validate
  const validatedFields = subscribeSchema.safeParse({
    email,
  })

  // Handle Failure
  if (!validatedFields.success) {
    return {
      errors: validatedFields.error.flatten().fieldErrors,
      message: 'Missing Fields. Failed to Subscribe.',
    }
  }

  // Handle Success (e.g., save to DB)
  // await db.subscribe(validatedFields.data.email)
  
  return {
    message: 'You have been subscribed successfully!',
  }
}

Step 2: Connect it to the Client Component

Now use the useActionState hook. Note: In React 19, this hook is imported from react, not react-dom.

// components/SubscribeForm.tsx
'use client'

import { useActionState } from 'react'
import { subscribe, FormState } from '@/app/actions'

const initialState: FormState = {
  message: null,
  errors: {},
}

export function SubscribeForm() {
  // Connect the action to the state
  const [state, formAction, isPending] = useActionState(subscribe, initialState)

  return (
    <form action={formAction} className="flex flex-col gap-4">
      <div>
        <label htmlFor="email">Email</label>
        <input 
          id="email" 
          name="email" 
          type="email" 
          className="border p-2 rounded" 
        />
        {/* Display Error for Email */}
        {state.errors?.email && (
          <p className="text-red-500 text-sm">{state.errors.email[0]}</p>
        )}
      </div>

      <button type="submit" disabled={isPending}>
        {isPending ? 'Submitting...' : 'Subscribe'}
      </button>

      {/* Display Global Message */}
      {state.message && (
        <p className="text-gray-700 font-medium">{state.message}</p>
      )}
    </form>
  )
}

---

1. Import Path: It is import { useActionState } from 'react'.
2. Return Types: Ensure your catch blocks or validation failures return the exact same shape as your initialState to avoid TypeScript yelling at you.
3. Zod Flatten: Using .flatten().fieldErrors makes the error object much easier to map in the JSX.

Happy coding! 🚀

[devMosaic]

After my Server Action successfully creates a new resource, what is the best practice to redirect the user to a different page, like /dashboard?

[Arjun-M]

Use the redirect function from next/navigation inside your Server Action. It's the recommended, reliable way to perform server-side redirects post-mutation.

// actions.ts
'use server'
import { redirect } from 'next/navigation'
    
export async function createPost() {
   // ... database logic
   redirect('/dashboard')
}

[devMosaic]

Thanks a lot ! let me give it a shot .