> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/colinhacks/zod/llms.txt
> Use this file to discover all available pages before exploring further.

# z.array()

> Define array schemas with length validations

## Basic Usage

Create an array schema that validates each element.

```typescript theme={null}
import { z } from 'zod';

const StringArray = z.array(z.string());

StringArray.parse(['a', 'b', 'c']); // ✓ Valid
StringArray.parse(['a', 1, 'c']);   // ✗ Invalid - contains number

type StringArray = z.infer<typeof StringArray>;
// string[]
```

## Signature

```typescript theme={null}
function array<T extends SomeType>(
  element: T,
  params?: string | ZodArrayParams
): ZodArray<T>
```

<ParamField path="element" type="ZodType" required>
  The schema to validate each array element against.
</ParamField>

<ParamField path="params" type="string | ZodArrayParams">
  Optional error message (string) or configuration object.
</ParamField>

## Properties

<ParamField path="element" type="ZodType">
  Access the element schema.

  ```typescript theme={null}
  const schema = z.array(z.string());
  schema.element; // ZodString
  ```
</ParamField>

## Methods

### min()

Set a minimum length for the array.

```typescript theme={null}
const AtLeastThree = z.array(z.string()).min(3);

AtLeastThree.parse(['a', 'b', 'c']);     // ✓ Valid
AtLeastThree.parse(['a', 'b']);          // ✗ Invalid - too short
AtLeastThree.parse(['a', 'b', 'c', 'd']); // ✓ Valid
```

**Signature:**

```typescript theme={null}
min(minLength: number, params?: string | ZodCheckMinLengthParams): this
```

<ParamField path="minLength" type="number" required>
  Minimum number of elements required.
</ParamField>

<ParamField path="params" type="string | object">
  Optional error message or configuration object.

  ```typescript theme={null}
  z.array(z.string()).min(3, 'At least 3 items required')
  z.array(z.string()).min(3, { message: 'Too few items' })
  ```
</ParamField>

### max()

Set a maximum length for the array.

```typescript theme={null}
const AtMostFive = z.array(z.number()).max(5);

AtMostFive.parse([1, 2, 3]);           // ✓ Valid
AtMostFive.parse([1, 2, 3, 4, 5]);     // ✓ Valid
AtMostFive.parse([1, 2, 3, 4, 5, 6]);  // ✗ Invalid - too long
```

**Signature:**

```typescript theme={null}
max(maxLength: number, params?: string | ZodCheckMaxLengthParams): this
```

<ParamField path="maxLength" type="number" required>
  Maximum number of elements allowed.
</ParamField>

<ParamField path="params" type="string | object">
  Optional error message or configuration object.

  ```typescript theme={null}
  z.array(z.number()).max(5, 'Too many items')
  z.array(z.number()).max(5, { message: 'Maximum 5 items' })
  ```
</ParamField>

### length()

Set an exact length for the array.

```typescript theme={null}
const ExactlyThree = z.array(z.boolean()).length(3);

ExactlyThree.parse([true, false, true]); // ✓ Valid
ExactlyThree.parse([true, false]);       // ✗ Invalid - wrong length
ExactlyThree.parse([true, false, true, false]); // ✗ Invalid - wrong length
```

**Signature:**

```typescript theme={null}
length(len: number, params?: string | ZodCheckLengthEqualsParams): this
```

<ParamField path="len" type="number" required>
  Exact number of elements required.
</ParamField>

<ParamField path="params" type="string | object">
  Optional error message or configuration object.

  ```typescript theme={null}
  z.array(z.boolean()).length(3, 'Must have exactly 3 items')
  ```
</ParamField>

### nonempty()

Require at least one element (equivalent to `.min(1)`).

```typescript theme={null}
const NonEmptyArray = z.array(z.string()).nonempty();

NonEmptyArray.parse(['item']);  // ✓ Valid
NonEmptyArray.parse([]);        // ✗ Invalid - empty array

type NonEmptyArray = z.infer<typeof NonEmptyArray>;
// [string, ...string[]]
```

<Note>
  The inferred type becomes a tuple type `[T, ...T[]]` to ensure at least one element at the type level.
</Note>

**Signature:**

```typescript theme={null}
nonempty(params?: string | ZodCheckMinLengthParams): this
```

<ParamField path="params" type="string | object">
  Optional error message or configuration object.

  ```typescript theme={null}
  z.array(z.string()).nonempty('Array cannot be empty')
  ```
</ParamField>

### unwrap()

Access the element schema.

```typescript theme={null}
const StringArray = z.array(z.string());
const ElementSchema = StringArray.unwrap();

type Element = z.infer<typeof ElementSchema>;
// string
```

**Signature:**

```typescript theme={null}
unwrap(): T
```

## Combining Validations

You can chain multiple validation methods:

```typescript theme={null}
const BoundedArray = z.array(z.number())
  .min(2, 'Need at least 2 numbers')
  .max(10, 'Cannot exceed 10 numbers');

BoundedArray.parse([1, 2, 3]);  // ✓ Valid
BoundedArray.parse([1]);         // ✗ Invalid - too short
BoundedArray.parse([...Array(11).fill(0)]); // ✗ Invalid - too long
```

## Complex Element Types

Arrays can contain any Zod schema:

### Objects

```typescript theme={null}
const Users = z.array(
  z.object({
    id: z.string(),
    name: z.string(),
    email: z.string().email(),
  })
);

type Users = z.infer<typeof Users>;
// Array<{ id: string; name: string; email: string }>
```

### Nested Arrays

```typescript theme={null}
const Matrix = z.array(z.array(z.number()));

type Matrix = z.infer<typeof Matrix>;
// number[][]

Matrix.parse([
  [1, 2, 3],
  [4, 5, 6],
  [7, 8, 9],
]); // ✓ Valid
```

### Unions

```typescript theme={null}
const MixedArray = z.array(z.union([z.string(), z.number()]));

type MixedArray = z.infer<typeof MixedArray>;
// (string | number)[]

MixedArray.parse(['a', 1, 'b', 2]); // ✓ Valid
```

## Convenience Method

You can also create arrays using the `.array()` method on any schema:

```typescript theme={null}
const StringArray = z.string().array();
// Equivalent to: z.array(z.string())

const MinThreeStrings = z.string().array().min(3);
// Equivalent to: z.array(z.string()).min(3)
```

## Type Inference

```typescript theme={null}
const schema = z.array(z.string()).min(1).max(10);

type Output = z.infer<typeof schema>;
// string[] (with runtime validation for 1-10 elements)

type Input = z.input<typeof schema>;
// string[] (same as output for arrays without transformations)
```

## Refinements

Add custom validation logic:

```typescript theme={null}
const UniqueNumbers = z.array(z.number())
  .refine(
    (arr) => new Set(arr).size === arr.length,
    'Array must contain unique values'
  );

UniqueNumbers.parse([1, 2, 3]);    // ✓ Valid
UniqueNumbers.parse([1, 2, 2, 3]); // ✗ Invalid - duplicate values
```

```typescript theme={null}
const SortedArray = z.array(z.number())
  .min(2)
  .refine(
    (arr) => arr.every((val, i, a) => i === 0 || val >= a[i - 1]),
    'Array must be sorted in ascending order'
  );

SortedArray.parse([1, 2, 3, 4]); // ✓ Valid
SortedArray.parse([1, 3, 2, 4]); // ✗ Invalid - not sorted
```

## Related

* [z.tuple()](/api/complex/tuple) - For fixed-length arrays with specific types
* [z.set()](/api/complex/set) - For sets with unique values
* [z.record()](/api/complex/record) - For key-value collections