Zod refine vs superRefine

Quick answer: when should you use zod refine?

Use `refine` when the base schema already describes the shape, but one business rule still needs custom logic. Examples include a password rule, a value that must be in a local allowlist, or an object that needs one cross-field check.

Basic refine example

Start with built-in Zod checks, then add `refine` only for the rule that cannot be expressed by `.min()`, `.email()`, `.regex()`, or an enum.

import { z } from "zod";

const UsernameSchema = z
  .string()
  .min(3)
  .max(24)
  .refine((value) => !value.includes("admin"), {
    message: "Username cannot contain reserved words",
  });

const result = UsernameSchema.safeParse(input);

Password confirmation with an error path

For object-level checks, put the error on the field the user can fix. A password confirmation rule should usually report against `confirmPassword`, not the whole object.

const SignupSchema = z
  .object({
    email: z.string().email(),
    password: z.string().min(12),
    confirmPassword: z.string(),
  })
  .refine((data) => data.password === data.confirmPassword, {
    path: ["confirmPassword"],
    message: "Passwords do not match",
  });

superRefine for multiple issues

`superRefine` is the better fit when one validation pass can add more than one issue, or when the issue path and code should be controlled explicitly.

const CartSchema = z
  .object({
    quantity: z.number().int(),
    coupon: z.string().optional(),
  })
  .superRefine((data, ctx) => {
    if (data.quantity <= 0) {
      ctx.addIssue({
        code: "custom",
        path: ["quantity"],
        message: "Quantity must be greater than zero",
      });
    }

    if (data.coupon === "EXPIRED") {
      ctx.addIssue({
        code: "custom",
        path: ["coupon"],
        message: "Coupon has expired",
      });
    }
  });

Async refine and safeParseAsync

Use async refinements for uniqueness, permissions, or external checks. Once a schema contains an async refinement, use `parseAsync` or `safeParseAsync` at the call site.

const InviteSchema = z
  .object({
    email: z.string().email(),
  })
  .refine(async ({ email }) => {
    return await canInviteEmail(email);
  }, {
    path: ["email"],
    message: "Email cannot receive invites",
  });

const result = await InviteSchema.safeParseAsync(body);

When not to use refine

Do not use refine for rules Zod already supports. Built-in checks are easier to read, easier to convert to JSON Schema, and easier for other developers to maintain.

• Use `.email()`, `.url()`, `.uuid()`, `.min()`, `.max()`, `.regex()`, and `z.enum()` before custom logic.
• Use `.transform()` when the value should change, not just pass or fail.
• Use `superRefine` when one object check can produce multiple field errors.

Refinements and JSON Schema output

Custom TypeScript callbacks do not have a faithful JSON Schema equivalent. If a refined Zod schema also needs JSON Schema or OpenAPI output, convert the structural part and keep the refinement as a separate runtime validation step.

Production checklist

Refinement bugs usually appear as confusing field messages or sync/async mismatches. Test both the happy path and every custom issue path.

• Add tests for valid data, invalid field values, invalid cross-field combinations, and async failure paths.
• Keep issue messages user-safe and avoid exposing database or permission details.
• Use `safeParse` or `safeParseAsync` when validation failure should become a controlled response.

Zod refine and superRefine comparison

Use FrameworkKit to generate the starter code, then review the output before shipping it in production.

Zod validation resources

FAQ

Related tools