Basic Usage
The .default() modifier provides a fallback value when the input is undefined.
import { z } from 'zod';
const schema = z.string().default('hello');
schema.parse('world'); // 'world'
schema.parse(undefined); // 'hello'
schema.parse(null); // throws error
.default() only applies to undefined values, not null or other invalid inputs.
Type Inference
The .default() modifier changes the input type to include undefined, but the output type excludes it:
const schema = z.string().default('hello');
type Input = z.input<typeof schema>; // string | undefined
type Output = z.output<typeof schema>; // string (no undefined)
Dynamic Defaults
You can provide a function that generates the default value:
const schema = z.object({
id: z.string().default(() => crypto.randomUUID()),
createdAt: z.date().default(() => new Date()),
});
const result1 = schema.parse({});
const result2 = schema.parse({});
// result1.id !== result2.id (different UUIDs)
Dynamic defaults are called each time the default is needed. For objects and arrays, this creates a new instance each time, preventing shared references.
In Object Schemas
Fields with .default() become optional in the input type:
const UserSchema = z.object({
name: z.string(),
role: z.string().default('user'),
isActive: z.boolean().default(true),
});
type UserInput = z.input<typeof UserSchema>;
// { name: string; role?: string | undefined; isActive?: boolean | undefined }
type User = z.output<typeof UserSchema>;
// { name: string; role: string; isActive: boolean }
UserSchema.parse({ name: 'John' });
// { name: 'John', role: 'user', isActive: true }
UserSchema.parse({ name: 'Jane', role: 'admin' });
// { name: 'Jane', role: 'admin', isActive: true }
Shallow Cloning
Default values are shallow cloned to prevent reference sharing:
const schema = z.object({
tags: z.array(z.string()).default(['default']),
});
const result1 = schema.parse({});
const result2 = schema.parse({});
result1.tags.push('new');
console.log(result2.tags); // ['default'] - not affected
Chaining with Optional
// Default on optional
const schema1 = z.string().optional().default('hello');
type Input1 = z.input<typeof schema1>; // string | undefined
type Output1 = z.output<typeof schema1>; // string
schema1.parse(undefined); // 'hello'
// Optional on default
const schema2 = z.string().default('hello').optional();
type Input2 = z.input<typeof schema2>; // string | undefined
type Output2 = z.output<typeof schema2>; // string | undefined
schema2.parse(undefined); // 'hello' (default applied)
const schema = z.string()
.transform(s => s.toUpperCase())
.default('hello');
type Input = z.input<typeof schema>; // string | undefined
type Output = z.output<typeof schema>; // string
schema.parse('world'); // 'WORLD'
schema.parse(undefined); // 'hello' (not transformed)
When chaining .default() after .transform(), the default value is applied at the output stage, so it bypasses the transformation.
Nested Defaults
const schema = z.object({
inner: z.string().default('inner-default'),
}).default({
inner: 'outer-default',
});
type Input = z.input<typeof schema>;
// { inner?: string | undefined } | undefined
type Output = z.output<typeof schema>;
// { inner: string }
schema.parse(undefined); // { inner: 'outer-default' }
schema.parse({}); // { inner: 'inner-default' }
schema.parse({ inner: undefined }); // { inner: 'inner-default' }
schema.parse({ inner: 'custom' }); // { inner: 'custom' }
Direction-Aware Behavior
Defaults only apply during parsing (forward direction), not during encoding:
const schema = z.string().default('hello');
// Parsing (forward)
schema.parse(undefined); // 'hello'
// Encoding (reverse)
z.encode(schema, undefined); // throws error - no default applied
Unwrapping
You can remove the default wrapper:
const withDefault = z.string().default('hello');
const withoutDefault = withDefault.unwrap(); // ZodString
// Legacy method (deprecated)
const withoutDefault2 = withDefault.removeDefault(); // same as unwrap()
Use Cases
- Configuration objects: Provide sensible defaults for optional config
- API responses: Fill in missing fields with default values
- Form data: Supply default values for unpopulated fields
- Database records: Set default values for optional columns
Comparison with .catch()
| Feature | .default() | .catch() |
|---|
| Triggers on | undefined only | Any validation failure |
| Use case | Optional inputs | Error recovery |
| Output type | Removes undefined | Keeps original type |