Field-Level Validation Errors with useActionState

Why Field-Level Errors?

Shaping the Action State

export type FieldErrors = {
  email?: string[];
  password?: string[];
};

export type SignupState = {
  errors?: FieldErrors;
  // value the user typed, so we can re-fill the form
  values?: { email?: string };
  // a top-level message for non-field errors
  message?: string;
};

export const initialState: SignupState = {};

Validating with Zod in the Action

import { z } from 'zod';

const SignupSchema = z.object({
  email: z.string().email('Enter a valid email'),
  password: z.string().min(8, 'At least 8 characters'),
});

const result = SignupSchema.safeParse({
  email: 'not-an-email',
  password: '123',
});

if (!result.success) {
  // { email: ['Enter a valid email'], password: ['At least 8 characters'] }
  console.log(result.error.flatten().fieldErrors);
}

The Server Action Signature

'use server';

import { z } from 'zod';
import type { SignupState } from './state';

const SignupSchema = z.object({
  email: z.string().email('Enter a valid email'),
  password: z.string().min(8, 'At least 8 characters'),
});

export async function signup(
  prevState: SignupState,
  formData: FormData,
): Promise<SignupState> {
  const email = String(formData.get('email') ?? '');
  const password = String(formData.get('password') ?? '');

  const parsed = SignupSchema.safeParse({ email, password });

  if (!parsed.success) {
    return {
      errors: parsed.error.flatten().fieldErrors,
      values: { email }, // keep email, never echo the password
    };
  }

  // ...persist the user here...
  return { message: 'Account created' };
}

Wiring useActionState

'use client';

import { useActionState } from 'react';
import { signup } from './actions';
import { initialState } from './state';

export function SignupForm() {
  const [state, formAction, isPending] = useActionState(
    signup,
    initialState,
  );

  return (
    <form action={formAction}>
      {/* inputs go here */}
      <button disabled={isPending}>
        {isPending ? 'Creating...' : 'Sign up'}
      </button>
    </form>
  );
}

Rendering an Inline Error

<div>
  <label htmlFor="email">Email</label>
  <input
    id="email"
    name="email"
    type="email"
    defaultValue={state.values?.email}
  />
  {state.errors?.email && (
    <p className="error">{state.errors.email[0]}</p>
  )}
</div>

Accessibility: Linking Errors to Inputs

<input
  id="email"
  name="email"
  type="email"
  defaultValue={state.values?.email}
  aria-invalid={!!state.errors?.email}
  aria-describedby="email-error"
/>
{state.errors?.email && (
  <p id="email-error" className="error" aria-live="polite">
    {state.errors.email[0]}
  </p>
)}

Preserving User Input

// in the action, on failure:
return {
  errors: parsed.error.flatten().fieldErrors,
  values: { email }, // safe to round-trip
  // password is intentionally omitted
};

// in the component:
<input name="email" defaultValue={state.values?.email} />
<input name="password" type="password" /> {/* always blank */}

A Pure Validation Helper You Can Test

type FieldErrors = { email?: string[]; password?: string[] };

function validateSignup(email: string, password: string): FieldErrors {
  const errors: FieldErrors = {};

  const emailOk = /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email);
  if (!emailOk) errors.email = ['Enter a valid email'];

  if (password.length < 8) errors.password = ['At least 8 characters'];

  return errors;
}

const e1 = validateSignup('bad', '123');
console.log(e1); // { email: [...], password: [...] }

const e2 = validateSignup('a@b.co', 'longenough');
console.log(Object.keys(e2).length === 0); // true

console.log(JSON.stringify(validateSignup('x@y.com', 'short')));

Multiple Errors per Field

{state.errors?.password && (
  <ul className="error-list">
    {state.errors.password.map((msg) => (
      <li key={msg}>{msg}</li>
    ))}
  </ul>
)}

Top-Level vs Field Errors

// in the action, after a successful parse:
try {
  await createUser(email, password);
} catch (err) {
  if (isUniqueViolation(err)) {
    return { errors: { email: ['Email already in use'] } };
  }
  return { message: 'Something went wrong. Please try again.' };
}

// in the component, above the fields:
{state.message && <p role="alert">{state.message}</p>}

Quick Check

Recap