parseWithZod
A helper that returns an overview of the submission by parsing the form data with the provided zod schema.
1const submission = parseWithZod(payload, options);
#Parameters
payload
It could be either the FormData or URLSearchParams object depending on how the form is submitted.
options
schema
Either a zod schema or a function that returns a zod schema.
async
Set it to true if you want to parse the form data with safeParseAsync method from the zod schema instead of safeParse.
errorMap
A zod error map to be used when parsing the form data.
formatError
A function that let you customize the error structure and include additional metadata as needed.
#Example
1import { parseWithZod } from '@conform-to/zod';
2import { useForm } from '@conform-to/react';
3import { z } from 'zod';
4
5const schema = z.object({
6 email: z.string().email(),
7 password: z.string(),
8});
9
10function Example() {
11 const [form, fields] = useForm({
12 onValidate({ formData }) {
13 return parseWithZod(formData, { schema });
14 },
15 });
16
17 // ...
18}
#Tips
Automatic type coercion
Conform will strip empty value and coerce the form data to the expected type by introspecting the schema and inject an extra preprocessing step. The following rules will be applied:
- If the value is an empty string / file, pass
undefined
to the schema - If the schema is
z.string()
, pass the value as is - If the schema is
z.number()
, trim the value and cast it with theNumber
constructor - If the schema is
z.boolean()
, treat the value astrue
if it equals toon
- If the schema is
z.date()
, cast the value with theDate
constructor - If the schema is
z.bigint()
, cast the value with theBigInt
constructor
You can override this behavior by setting up your own z.preprocess
step in the schema.
Note: There are several bug reports on Zod's repository regarding the behaviour of
z.preprocess
since v3.22, like https://github.com/colinhacks/zod/issues/2671 and https://github.com/colinhacks/zod/issues/2677. If you are experiencing any issues, please downgrade to v3.21.4.
1const schema = z.object({
2 amount: z.preprocess((value) => {
3 // If no value is provided, return `undefined`
4 if (!value) {
5 return undefined;
6 }
7
8 // Clear the formatting and cast the value to number
9 return Number(value.trim().replace(/,/g, ''));
10 }, z.number()),
11});
Default values
Conform already preprocesses empty values to undefined
. Add .default()
to your schema to define a default value that will be returned instead.
Zod will return the default value if the input is undefined
after preprocessing. This also has the effect of changing the schema return type.
1const schema = z.object({
2 foo: z.string(), // string | undefined
3 bar: z.string().default('bar'), // string
4 baz: z.string().nullable().default(null), // string | null
5});