Zod refine unknown error message when applied to more paths

Handling Zod Refine Errors Across Multiple Fields

When working with Zod and React Hook Form, you may encounter challenges in validating multiple fields simultaneously and displaying error messages across all affected fields. For example, if two fields need to satisfy a condition, the error must appear in both fields until the condition is resolved.

This article demonstrates how to address this issue, including fixing "unknown" error messages and ensuring proper error handling for all fields.

Problem

Given the following validation schema, we want to ensure that fieldTwo + fieldThree === fieldOne, and display the error message for both fieldTwo and fieldThree when the condition fails.

const schema = z
  .object({
    fieldOne: z.number(),
    fieldTwo: z.number(),
    fieldThree: z.number(),
  })
  .refine((data) => data.fieldTwo + data.fieldThree === data.fieldOne, {
    message: 'fieldTwo plus fieldThree must be equal to fieldOne',
    path: ['fieldTwo', 'fieldThree'],
  })

Challenges

1. Unknown Error Messages: Errors may appear as "unknown" instead of the custom message.
2. Error Display in One Field: Errors may only appear in the first field listed in the path array.
3. Error Disappearance: Errors disappear from one field but persist in another when the condition is resolved.

Solution

To resolve these issues, use the superRefine method with ctx.addIssue for granular control over validation and error assignment.

Updated Schema

const schema = z
  .object({
    fieldOne: z.coerce.number(),
    fieldTwo: z.coerce.number(),
    fieldThree: z.coerce.number(),
  })
  .superRefine((args, ctx) => {
    if (args.fieldTwo + args.fieldThree !== args.fieldOne) {
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        path: ['fieldTwo'],
        message: 'fieldTwo + fieldThree must = fieldOne',
      })
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        path: ['fieldThree'],
        message: 'fieldTwo + fieldThree must = fieldOne',
      })
    }
  })

React Hook Form Integration

Here’s how to integrate the schema with React Hook Form to ensure proper error handling:

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

const TestForm = () => {
  const form = useForm({
    resolver: zodResolver(schema),
  })

  const onSubmit = (data) => {
    console.log('Submitted:', data)
  }

  return (
    <form onSubmit={form.handleSubmit(onSubmit)}>
      <div>
        <label>Field One</label>
        <input {...form.register('fieldOne')} type="number" />
        <p>{form.formState.errors.fieldOne?.message}</p>
      </div>
      <div>
        <label>Field Two</label>
        <input {...form.register('fieldTwo')} type="number" />
        <p>{form.formState.errors.fieldTwo?.message}</p>
      </div>
      <div>
        <label>Field Three</label>
        <input {...form.register('fieldThree')} type="number" />
        <p>{form.formState.errors.fieldThree?.message}</p>
      </div>
      <button type="submit">Submit</button>
    </form>
  )
}

export default TestForm

Explanation

1. superRefine: Allows adding custom validation logic and assigning errors to multiple fields.
2. ctx.addIssue: Adds errors to specific paths, ensuring they appear on all relevant fields.
3. React Hook Form Integration: Maps Zod validation to React Hook Form’s error management, ensuring proper error display.

FAQs

Why does refine not work for multiple fields?

refine applies validation to a single path. When you need to assign errors to multiple fields, superRefine is required.

Why do errors persist in one field after resolving the condition?

This may occur if React Hook Form doesn’t update its state correctly. Using ctx.addIssue ensures that errors are explicitly added or removed based on the validation logic.

Can I use this approach for more complex validations?

Yes, superRefine is highly flexible and can handle complex validation logic, including interdependent fields and dynamic conditions.

Conclusion

By using Zod’s superRefine method and React Hook Form, you can effectively manage complex validations involving multiple fields. This ensures accurate error messages and a seamless user experience.