Fill missing settings with safe values
Configuration parsing
Zod · Module
z.default
.default() supplies a fallback when a schema receives undefined. It returns that fallback immediately and can also generate defaults through a function.
How it works
Call .default() on an existing schema to provide a fallback for undefined input. The fallback is returned immediately rather than being parsed through the wrapped schema, while a function can generate a fresh default each time one is needed.
Syntax
schema.default(value)Parameters
| Name | Type | Description |
|---|---|---|
value | output type or () => output type | The fallback value, or a function that produces it when undefined input needs a default; it must be assignable to the schema output type. |
Returns
A schema that accepts undefined as input and returns the configured default when the input is undefined.
Key points
- Use
.default(value)to attach a fallback to an existing schema. - The method can be chained directly after a base schema such as
z.string(). - Parsing undefined returns the configured fallback.
- Defaults let a schema provide a value when an object key is absent.
- A defaulted field is optional in the input type.
Common mistakes
- The default must satisfy the schema's output type, not merely its input type.
- The default bypasses the wrapped schema's parsing and checks.
- Use a function when the fallback should be generated anew for each missing value.
Example: Applying a default to a string schema
import { z } from "zod";
const name = z.string().default("Anonymous");
console.log(name.parse(undefined)); // "Anonymous"
console.log(name.parse("Ada")); // "Ada"Creates a string schema that supplies "Anonymous" when the parsed input is undefined.
When to use it
Provide values for omitted fields
Object validation
Generate a fresh fallback per missing input
Dynamic initialization
Interview questions
QWhat does .default() do when parsing undefined?
.default(value) makes undefined input produce the supplied fallback. It also makes the schema's input accept an absent value while preserving the schema's output type.
Follow-up: How does it differ from .prefault()? .default() returns the fallback directly, whereas .prefault() parses the fallback through the schema.
QDoes the default value pass through the schema?
The default is returned eagerly, so the wrapped schema does not validate or transform that fallback. The fallback therefore needs to be assignable to the schema's output type.
Follow-up: Why can a transformed schema require an output-shaped default? Because the default skips the transformation pipeline and is emitted as the result.
QWhen should the default be a function?
Pass a callback instead of a fixed value when defaults must be generated dynamically. Zod re-executes that callback whenever it needs to create a default.
Follow-up: What would you use for a default that must still undergo validation? .prefault() supplies a pre-parse value and keeps parsing active.
Related
z.prefaultz.optionalz.objectz.string