When you need to implement custom validation logic that goes beyond Zod's built-in type and value checks, you can use the .refine() and .superRefine() methods. These methods allow you to add your own rules to a Zod schema.

The .refine() method lets you attach a custom validation function to a schema. This function receives the value being validated and should return true if the value is valid or false if not. You can also provide a custom error message to display when validation fails.

If you need to perform complex validation that may depend on multiple fields or want to add custom error paths, .superRefine() gives you more control. It provides access to a validation context, letting you add errors for specific paths or with custom messages.

Using .refine() is most common when you want to enforce a rule that cannot be expressed through Zod's standard schema types. For example, you might want to check that a password is strong enough, or that an email address does not belong to a disposable email provider.

Suppose you want to ensure that a password field in your form has at least 8 characters, contains both letters and numbers, and does not include the word "password". You can add this logic to your Zod schema using refine like this:

import { z } from "zod";

const passwordSchema = z.string().refine(
  (val) => {
    const hasMinLength = val.length >= 8;
    const hasLetter = /[a-zA-Z]/.test(val);
    const hasNumber = /[0-9]/.test(val);
    const doesNotContainPassword = !val.toLowerCase().includes("password");
    return hasMinLength && hasLetter && hasNumber && doesNotContainPassword;
  },
  {
    message:
      "Password must be at least 8 characters, contain letters and numbers, and not include the word 'password'."
  }
);

This schema uses refine to enforce all the password rules in a single validation step. If any of the conditions fail, the provided error message will be shown to the user. This approach keeps your custom validation logic close to your schema definition, making it easy to maintain and update as requirements change.