Validate submitted form data before business logic
Server actions and route handlers
Conform · Function
parseWithZod
Parses FormData or URLSearchParams with a Zod schema and returns a Conform submission result. Successful submissions expose parsed data; unsuccessful ones contain validation errors.
How it works
Pass FormData or URLSearchParams and an options object containing a Zod schema. The helper parses the input and produces a submission result whose status indicates success or failure; successful results expose the parsed value, while failures can be returned through reply(). Automatic preprocessing removes empty values and coerces values according to the schema unless disabled.
Syntax
parseWithZod(payload, options)Parameters
| Name | Type | Description |
|---|---|---|
payload | FormData | URLSearchParams | Submitted form input, either a FormData or URLSearchParams object. |
options | ParseWithZodOptions | Parsing configuration, including schema and optional async, errorMap, formatError, and disableAutoCoercion settings. |
Returns
A submission object containing either the parsed value on success or validation errors on failure.
Key points
- It turns submitted form data into a Conform submission result by validating it with a Zod schema.
- The input can be FormData or URLSearchParams, so the same API supports common browser submission representations.
- options.schema accepts either a schema instance or a function that produces a schema.
- Set async to true when validation must use Zod's asynchronous safeParseAsync path.
- errorMap lets callers supply Zod's error mapping behavior during parsing.
- formatError can reshape validation errors and add application-specific metadata.
- Default preprocessing removes empty values and coerces submitted strings to types inferred from the schema.
Common mistakes
- Automatic coercion is enabled by default. Disable it only when you intend to control preprocessing and type conversion yourself.
- Use the dedicated v4 subpath when the project uses Zod 4; the default package import targets Zod 3.
Example: Validate submitted FormData
import { parseWithZod } from '@conform-to/zod';
import { z } from 'zod';
const schema = z.object({
email: z.string().email(),
age: z.coerce.number().int().min(18),
});
export async function action({ request }) {
const formData = await request.formData();
const submission = parseWithZod(formData, { schema });
if (submission.status !== 'success') {
return submission.reply();
}
return { user: submission.value };
}Reads submitted form data, validates it against the schema, and returns either a failure reply or the typed parsed value.
When to use it
Reuse the same Zod schema in useForm onValidate
Client-side form validation
Customize asynchronous parsing, error mapping, or error formatting
Advanced validation pipelines
Interview questions
QWhat does parseWithZod do?
parseWithZod accepts submitted FormData or URLSearchParams plus options containing a Zod schema. It returns a submission object representing either the parsed value or validation errors.
Follow-up: How would you validate asynchronously? Set options.async to true so parsing uses the schema's safeParseAsync method.
QWhat can be supplied as the schema?
The schema option may be a Zod schema or a function that returns one. The function form lets schema selection depend on the submitted data or other runtime context.
Follow-up: How can error output be customized? Provide errorMap for Zod error mapping or formatError to shape errors and attach metadata.
QHow does automatic coercion affect parsing?
By default, the helper strips empty values and infers coercion from the Zod schema through internal preprocessing. Set disableAutoCoercion to true when that behavior should be managed explicitly.
Follow-up: Why might explicit preprocessing be useful? It gives the application precise control over how strings, empty values, and other form representations become schema inputs.
Related
@conform-to/zod@conform-to/zod/v4coerceFormValuegetZodConstraintsafeParsesafeParseAsync