Zod coerce for query params and forms

Quick answer: how do you turn a string param into a number with Zod?

Wrap the field in `z.coerce.number()`. Query strings, route params, form fields, and env vars all arrive as strings, and coercion runs a JavaScript cast before validation so the parsed output is correctly typed. Use `z.coerce.date()` for dates, but avoid `z.coerce.boolean()` for flags because it treats any non-empty string as true.

Coerce numbers from query strings

A pagination or filter query gives you strings. `z.coerce.number()` casts before validating, so you can still chain `.int()`, `.min()`, and `.max()` to keep the value in range.

import * as z from "zod";

const QuerySchema = z.object({
  page: z.coerce.number().int().min(1).default(1),
  pageSize: z.coerce.number().int().max(100).default(20),
});

QuerySchema.parse({ page: "3", pageSize: "50" });
// { page: 3, pageSize: 50 }

Coerce dates safely

`z.coerce.date()` runs `new Date(value)` and rejects values that produce an Invalid Date. This is convenient for URL filters, but validate the range afterward if only certain dates are allowed.

const RangeSchema = z.object({
  from: z.coerce.date(),
  to: z.coerce.date(),
});

const range = RangeSchema.parse({
  from: "2026-01-01",
  to: "2026-06-30",
});
// { from: Date, to: Date }

The z.coerce.boolean() trap (and z.stringbool fix)

`z.coerce.boolean()` calls `Boolean(value)`. Because any non-empty string is truthy, the string "false" becomes `true`. For real query-string flags, use `z.stringbool()` in Zod 4, which understands "true"/"false", "1"/"0", and "yes"/"no".

// Trap: "false" is a non-empty string -> true
z.coerce.boolean().parse("false"); // true

// Fix in Zod 4
z.stringbool().parse("false"); // false
z.stringbool().parse("yes");   // true

Where coercion belongs

Coercion is for boundaries where data arrives as text. Keep it out of your internal domain models, which should already hold typed values.

• Use coercion for URL query params, route params, form submissions, env vars, and CSV cells.
• Do not coerce inside internal types that already hold numbers, dates, or booleans.
• Combine coercion with `safeParse` so bad params return a structured error instead of throwing.
• Prefer `z.stringbool()` over `z.coerce.boolean()` for any string flag.

Zod coercion helpers

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

Zod validation resources

FAQ

Related tools