Alternative primitive inputs
A field legitimately accepts multiple primitive types, such as an identifier supplied as either text or a number.
Zod · Type Alias
ZodUnion
ZodUnion is Zod’s schema type for logical OR validation. It accepts an input when any member schema succeeds, testing members in order and returning the first successful parsed value.
How it works
ZodUnion represents a logical OR between multiple schemas. The union tries its options in declaration order and returns the first successfully parsed value; if none match, parsing fails with issues from the attempted options.
Syntax
z.union([schemaA, schemaB, ...])Parameters
| Name | Type | Description |
|---|---|---|
options | ZodType[] | An array of schemas representing the alternatives in the union. |
Returns
A Zod union schema whose inferred output is the union of the member schemas' outputs.
Key points
- ZodUnion expresses that a value may satisfy any one of several schemas.
- Parsing stops at the first successful option and returns that option's parsed value.
- Construct a union by passing an array of schemas to
z.union. - A value is accepted when at least one member schema validates it.
Common mistakes
- Option order affects which schema handles an input and which successful result is returned.
- Prefer a discriminated union for large object unions when a shared discriminator can select the branch directly.
Example: Validate a string-or-number value
import { z } from "zod";
const stringOrNumber = z.union([z.string(), z.number()]);
console.log(stringOrNumber.parse("hello"));
console.log(stringOrNumber.parse(42));Creates a schema accepting either a string or a number, then parses one value of each kind.
When to use it
Small untagged object variants
A payload can have one of several shapes and no shared discriminator is available.
Recursive data structures
A recursive JSON-like value may be a primitive, array, or record.
Interview questions
QWhat does a Zod union do, and how is it created?
A union models a logical OR, such as string or number. Create one with z.union([z.string(), z.number()]), and Zod checks the options in order until one succeeds.
Follow-up: How can parsing be made more efficient for object variants? Use z.discriminatedUnion() with a shared discriminator key so Zod can choose the relevant option directly.
QHow does Zod choose a union branch?
Zod tests the input against each option in declaration order. It returns the first value that validates successfully; if every option fails, parsing fails.
Follow-up: Why can branch order matter? If multiple schemas accept the same input, the first successful schema determines the parsed result and any transformations it applies.
QWhen should you use a discriminated union instead?
A discriminated union is composed of object schemas sharing a key such as status. Zod reads that discriminator to select one option, which is generally faster and produces errors for the selected option.
Follow-up: When is a regular union still appropriate? Use it when variants do not share a suitable discriminator or when the union is small and straightforward.
Related
z.unionz.discriminatedUnionZodDiscriminatedUnionz.orz.infer