Conform Documentation

The conformZodMessage object provides special custom messages that allow you to control how Conform handles Zod validation results, which is particularly useful for managing asynchronous validation or conditional validation logic.

By using these specific messages within a Zod superRefine or refine block, you can signal to Conform how to proceed when certain conditions are met:

• conformZodMessage.VALIDATION_SKIPPED: Tells Conform that validation for this field was skipped. Conform will then use the previous validation result instead of treating this as an error.
• conformZodMessage.VALIDATION_UNDEFINED: Tells Conform that validation is not defined for the current context. Conform will fallback to server-side validation.

import { conformZodMessage } from '@conform-to/zod';

// Example usage in a Zod refinement
ctx.addIssue({
  code: 'custom',
  message: conformZodMessage.VALIDATION_SKIPPED,
});

Conform handles async validation (like checking if an email is unique) by falling back to server validation when client-side validation is insufficient.

1. On the Client: Use a schema creator that returns a schema without the async implementation. In the onValidate callback, if the async function is missing, use ctx.addIssue with message: conformZodMessage.VALIDATION_UNDEFINED and fatal: true. This signals Conform to trigger a server-side validation.
2. On the Server: Use parseWithZod with the async: true option and provide the actual implementation of the async logic within the schema.

import { refine } from '@conform-to/zod';

function createSchema(
  options?: { isEmailUnique: (email: string) => Promise<boolean>; },
) {
  return z.object({
    email: z.string().email().pipe(
      z.string().superRefine((email, ctx) => {
        if (typeof options?.isEmailUnique !== 'function') {
          ctx.addIssue({
            code: 'custom',
            message: conformZodMessage.VALIDATION_UNDEFINED,
            fatal: true,
          });
          return;
        }

        return options.isEmailUnique(email).then((isUnique) => {
          if (!isUnique) {
            ctx.addIssue({
              code: 'custom',
              message: 'Email is already used',
            });
          }
        });
      }),
    ),
  });
}

export function action() {
  const formData = await request.formData();
  const submission = await parseWithZod(formData, {
    schema: createSchema({
      async isEmailUnique(email) { /* ... */ },
    }),
    async: true,
  });
}

export default function Signup() {
  const lastResult = useActionData();
  const [form] = useForm({
    lastResult,
    onValidate({ formData }) {
      return parseWithZod(formData, {
        schema: createSchema(),
      });
    },
  });
}

By default, parseWithZod automatically strips empty values and coerces form values to the types defined in your schema using an internal coerceFormValue helper.

If you need to implement custom parsing logic (for example, handling specific string formats before converting them to numbers), set disableAutoCoercion: true in the options and use Zod's z.preprocess or similar methods to manage the values yourself.

import { parseWithZod } from '@conform-to/zod';
import { useForm } from '@conform-to/react';
import { z } from 'zod';

const schema = z.object({
  // Strip empty value and coerce the number yourself
  amount: z.preprocess((value) => {
    if (typeof value !== 'string') {
      return value;
    }

    if (value === '') {
      return undefined;
    }

    return Number(value.trim().replace(/,/g, ''));
  }, z.number()),
});

function Example() {
  const [form, fields] = useForm({
    onValidate({ formData }) {
      return parseWithZod(formData, {
        schema,
        disableAutoCoercion: true,
      });
    },
  });

  // ...
}

When you pass a Standard Schema as the first argument to useForm(schema, options), Conform enables schema-derived type inference and automatic validation.

Key behaviors when using a schema:

• Conform runs schema validation before the onValidate handler.
• onValidate can still be used to add or replace validation errors.
• ctx.schemaValue provides the parsed schema value when validation succeeds.
• schemaOptions are forwarded to the configured schema validator.

To support non-Standard Schema types, use configureForms.

import { useForm } from '@conform-to/react/future';
import { z } from 'zod';

const schema = z.object({
  email: z.string().email('Email is invalid'),
  password: z.string().min(8, 'Password must be at least 8 characters'),
});

function LoginForm() {
  const { form, fields } = useForm(schema, {
    shouldValidate: 'onBlur',
  });

  return (
    <form {...form.props}>
      <input
        type="email"
        name={fields.email.name}
        defaultValue={fields.email.defaultValue}
      />
      <div>{fields.email.errors}</div>
      <input
        type="password"
        name={fields.password.name}
        defaultValue={fields.password.defaultValue}
      />
      <div>{fields.password.errors}</div>

      <button type="submit" disabled={!form.valid}>
        Login
      </button>
    </form>
  );
}