Arrays

Zod provides various ways to validate arrays.

Basic Usage

import { z } from "zod";

// Create array schemas
const stringArray = z.array(z.string());
const numberArray = z.array(z.number());

// Alternative syntax
const stringArray2 = z.string().array();
const numberArray2 = z.number().array();

// Validation
stringArray.parse(["a", "b", "c"]); // passes
stringArray.parse(["a", 123, "c"]); // fails

Non-empty Arrays

Use .nonempty() to ensure an array contains at least one element:

const nonEmptyStrings = z.string().array().nonempty();
// type is [string, ...string[]]

nonEmptyStrings.parse([]); // fails: Array cannot be empty
nonEmptyStrings.parse(["hello"]); // passes

Length Validation

// Minimum length
z.string().array().min(5); // at least 5 elements

// Maximum length
z.string().array().max(10); // at most 10 elements

// Exact length
z.string().array().length(3); // exactly 3 elements

// Combined
z.string().array().min(2).max(5); // between 2 and 5 elements

Custom Error Messages

z.array(z.string()).nonempty({
  message: "Array must contain at least one element",
});

z.array(z.string()).min(3, {
  message: "Array must contain at least 3 elements",
});

z.array(z.string()).max(5, {
  message: "Array must not contain more than 5 elements",
});

Complex Arrays

// Array of objects
const User = z.object({
  id: z.string(),
  name: z.string(),
});
const UserArray = z.array(User);

// Array of union types
const mixedArray = z.array(z.union([z.string(), z.number()]));
mixedArray.parse(["hello", 42, "world"]); // passes

// Nested arrays
const matrix = z.array(z.array(z.number()));
matrix.parse([
  [1, 2, 3],
  [4, 5, 6],
]); // passes

Array Element Transformation

// Transform each element in the array
const numberStrings = z
  .array(z.string())
  .transform(arr => arr.map(Number));

numberStrings.parse(["1", "2", "3"]); // => [1, 2, 3]

// Filter array elements
const nonEmptyStrings = z
  .array(z.string())
  .transform(arr => arr.filter(str => str.length > 0));

nonEmptyStrings.parse(["", "hello", "", "world"]); // => ["hello", "world"]