Fixed-length strings
Require a fixed-size identifier, such as a five-code-point username or short token.
Zod · Module
.length
.length(n) requires a string or array to have exactly n units according to Zod’s counting rules. Strings are measured in Unicode code points; arrays are measured by item count.
How it works
.length(n) adds an exact-length constraint to a string or array schema. For strings, Zod counts Unicode code points rather than UTF-16 code units; for arrays, it requires exactly the specified number of items.
Syntax
z.string().length(n)
z.array(elementSchema).length(n)Parameters
| Name | Type | Description |
|---|---|---|
length | number | The exact length or item count required by the schema. |
Returns
A schema that validates strings or arrays with exactly the specified length; parsing returns the original validated value.
Key points
- Call
.length(n)afterz.string()to require an exact string length. - Array schemas use the same method to require an exact number of elements.
- An astral-plane emoji counts as one code point even though JavaScript represents it with two UTF-16 units.
- A base character plus a combining mark counts as two code points.
- A ZWJ emoji sequence is counted by its constituent code points rather than as one visible glyph.
Common mistakes
- String length is based on Unicode code points, so JavaScript's UTF-16 code-unit length can differ.
- Visually perceived characters are not always counted as one: combining marks and zero-width-joiner sequences contribute multiple code points.
Example: Validate an exact string length
import { z } from "zod";
const username = z.string().length(5);
console.log(username.parse("alice")); // "alice"
// username.parse("al"); // throws a ZodErrorCreates a string schema that accepts exactly five Unicode code points.
When to use it
Fixed-size arrays
Ensure a tuple-like collection has an exact number of elements while retaining array-item validation.
Unicode-aware validation
Validate Unicode-sensitive input where code-point counting is preferable to UTF-16 unit counting.
Interview questions
QWhat does z.string().length(5) enforce?
Use z.string().length(n) when a string must contain exactly n Unicode code points. Parsing succeeds only when the constraint is met.
Follow-up: How would you validate an exact number of array elements? Use z.array(elementSchema).length(n), which checks the array item count.
QWhat unit does Zod use for string length?
It rejects strings whose Unicode code-point count is not exactly the supplied number. This differs from counting UTF-16 code units in JavaScript.
Follow-up: Why can an emoji expose this difference? An emoji outside the Basic Multilingual Plane can count as one code point but occupy two UTF-16 units.
QDoes .length() apply only to strings?
The method is also available on arrays, where .length(5) means the array must contain exactly five items. The element schema still validates each item.
Follow-up: How can a transformed string expose its JavaScript length? Pipe into z.transform(val => val.length), while remembering that this uses JavaScript's length behavior.
Related
z.string().min()z.string().max()z.array()z.transform()