Package Exports
- zod
- zod/package.json
- zod/v3
- zod/v4
- zod/v4-mini
- zod/v4/core
- zod/v4/locales
- zod/v4/locales/ar.d.ts
- zod/v4/locales/ar.js
- zod/v4/locales/az.d.ts
- zod/v4/locales/az.js
- zod/v4/locales/be.d.ts
- zod/v4/locales/be.js
- zod/v4/locales/ca.d.ts
- zod/v4/locales/ca.js
- zod/v4/locales/cs.d.ts
- zod/v4/locales/cs.js
- zod/v4/locales/de.d.ts
- zod/v4/locales/de.js
- zod/v4/locales/en.d.ts
- zod/v4/locales/en.js
- zod/v4/locales/es.d.ts
- zod/v4/locales/es.js
- zod/v4/locales/fa.d.ts
- zod/v4/locales/fa.js
- zod/v4/locales/fi.d.ts
- zod/v4/locales/fi.js
- zod/v4/locales/fr-CA.d.ts
- zod/v4/locales/fr-CA.js
- zod/v4/locales/fr.d.ts
- zod/v4/locales/fr.js
- zod/v4/locales/he.d.ts
- zod/v4/locales/he.js
- zod/v4/locales/hu.d.ts
- zod/v4/locales/hu.js
- zod/v4/locales/id.d.ts
- zod/v4/locales/id.js
- zod/v4/locales/index.d.ts
- zod/v4/locales/index.js
- zod/v4/locales/it.d.ts
- zod/v4/locales/it.js
- zod/v4/locales/ja.d.ts
- zod/v4/locales/ja.js
- zod/v4/locales/kh.d.ts
- zod/v4/locales/kh.js
- zod/v4/locales/ko.d.ts
- zod/v4/locales/ko.js
- zod/v4/locales/mk.d.ts
- zod/v4/locales/mk.js
- zod/v4/locales/ms.d.ts
- zod/v4/locales/ms.js
- zod/v4/locales/nl.d.ts
- zod/v4/locales/nl.js
- zod/v4/locales/no.d.ts
- zod/v4/locales/no.js
- zod/v4/locales/ota.d.ts
- zod/v4/locales/ota.js
- zod/v4/locales/pl.d.ts
- zod/v4/locales/pl.js
- zod/v4/locales/pt.d.ts
- zod/v4/locales/pt.js
- zod/v4/locales/ru.d.ts
- zod/v4/locales/ru.js
- zod/v4/locales/sl.d.ts
- zod/v4/locales/sl.js
- zod/v4/locales/sv.d.ts
- zod/v4/locales/sv.js
- zod/v4/locales/ta.d.ts
- zod/v4/locales/ta.js
- zod/v4/locales/th.d.ts
- zod/v4/locales/th.js
- zod/v4/locales/tr.d.ts
- zod/v4/locales/tr.js
- zod/v4/locales/ua.d.ts
- zod/v4/locales/ua.js
- zod/v4/locales/ur.d.ts
- zod/v4/locales/ur.js
- zod/v4/locales/vi.d.ts
- zod/v4/locales/vi.js
- zod/v4/locales/zh-CN.d.ts
- zod/v4/locales/zh-CN.js
- zod/v4/locales/zh-TW.d.ts
- zod/v4/locales/zh-TW.js
- zod/v4/mini
Readme
Zod
TypeScript-first schema validation with static type inference
by @colinhacks
Featured sponsor: Jazz
Read the docs →
What is Zod?
Zod is a TypeScript-first validation library. Define a schema and parse some data with it. You'll get back a strongly typed, validated result.
import { z } from "zod/v4";
const User = z.object({
name: z.string(),
});
// some untrusted data...
const input = {
/* stuff */
};
// the parsed result is validated and type safe!
const data = User.parse(input);
// so you can use it with confidence :)
console.log(data.name);Features
- Zero external dependencies
- Works in Node.js and all modern browsers
- Tiny:
2kbcore bundle (gzipped) - Immutable API: methods return a new instance
- Concise interface
- Works with TypeScript and plain JS
- Built-in JSON Schema conversion
- Extensive ecosystem
Installation
npm install zodBasic usage
Before you can do anything else, you need to define a schema. For the purposes of this guide, we'll use a simple object schema.
import { z } from "zod/v4";
const Player = z.object({
username: z.string(),
xp: z.number(),
});Parsing data
Given any Zod schema, use .parse to validate an input. If it's valid, Zod returns a strongly-typed deep clone of the input.
Player.parse({ username: "billie", xp: 100 });
// => returns { username: "billie", xp: 100 }Note — If your schema uses certain asynchronous APIs like async refinements or transforms, you'll need to use the .parseAsync() method instead.
const schema = z.string().refine(async (val) => val.length <= 8);
await schema.parseAsync("hello");
// => "hello"Handling errors
When validation fails, the .parse() method will throw a ZodError instance with granular information about the validation issues.
try {
Player.parse({ username: 42, xp: "100" });
} catch (err) {
if (error instanceof z.ZodError) {
err.issues;
/* [
{
expected: 'string',
code: 'invalid_type',
path: [ 'username' ],
message: 'Invalid input: expected string'
},
{
expected: 'number',
code: 'invalid_type',
path: [ 'xp' ],
message: 'Invalid input: expected number'
}
] */
}
}To avoid a try/catch block, you can use the .safeParse() method to get back a plain result object containing either the successfully parsed data or a ZodError. The result type is a discriminated union, so you can handle both cases conveniently.
const result = Player.safeParse({ username: 42, xp: "100" });
if (!result.success) {
result.error; // ZodError instance
} else {
result.data; // { username: string; xp: number }
}Note — If your schema uses certain asynchronous APIs like async refinements or transforms, you'll need to use the .safeParseAsync() method instead.
const schema = z.string().refine(async (val) => val.length <= 8);
await schema.safeParseAsync("hello");
// => { success: true; data: "hello" }Inferring types
Zod infers a static type from your schema definitions. You can extract this type with the z.infer<> utility and use it however you like.
const Player = z.object({
username: z.string(),
xp: z.number(),
});
// extract the inferred type
type Player = z.infer<typeof Player>;
// use it in your code
const player: Player = { username: "billie", xp: 100 };In some cases, the input & output types of a schema can diverge. For instance, the .transform() API can convert the input from one type to another. In these cases, you can extract the input and output types independently:
const mySchema = z.string().transform((val) => val.length);
type MySchemaIn = z.input<typeof mySchema>;
// => string
type MySchemaOut = z.output<typeof mySchema>; // equivalent to z.infer<typeof mySchema>
// number