Bound string length
Usernames, labels, and other text fields must stay below a storage or UI limit.
Zod · Module
.max
.max() adds an inclusive upper bound to a Zod schema. Its meaning depends on the schema: string length, array item count, file size, or a comparable maximum for dates and bigints.
How it works
.max() adds an upper-bound check to a schema. For strings it limits length, while the same method on arrays and files limits item count or file size; the page also documents date and bigint variants.
Syntax
schema.max(value, params?)Parameters
| Name | Type | Description |
|---|---|---|
value | number | bigint | Date | Maximum permitted value, length, count, date, bigint, or file size, depending on the schema type. |
params | error configuration | Optional error customization configuration. |
Returns
The same Zod schema instance with an added maximum constraint, enabling method chaining.
Key points
- Call
.max(n)afterz.string()to impose an upper bound ofnon string length. - On arrays,
.max(n)allows at mostnelements while still validating each element against the element schema. - For file schemas, the limit applies to the file's size in bytes.
- Date schemas use
.max(date)to reject dates later than the supplied maximum, and the example demonstrates an error option.
Common mistakes
- In current Zod 4.5 documentation, string length checks count Unicode code points rather than UTF-16 code units, so astral characters such as emoji affect the limit differently than in earlier behavior.
- A user-perceived grapheme can contain multiple code points, so
.max()does not necessarily limit visible characters as users count them.
Example: Limit a string's length
import { z } from "zod";
const username = z.string().max(12);
console.log(username.safeParse("Ada").success); // true
console.log(username.safeParse("This name is too long").success); // falseCreates a string schema that accepts values whose length does not exceed 12.
When to use it
Cap array size
A request should accept only a limited number of records.
Restrict file size
Uploads must stay within an application or infrastructure limit.
Enforce upper numeric or temporal bounds
A timestamp or bigint must not exceed a defined boundary.
Interview questions
QWhat does Zod's .max() method do?
.max(value) adds an inclusive upper bound to the schema's relevant measurement. On strings it constrains length; on arrays it constrains the number of elements, and on files it constrains byte size.
Follow-up: How would you enforce an exact string length? Use .length(n), which requires the string to have exactly n characters under the documented string-length semantics.
QHow do you limit a string's maximum length?
For a string schema, z.string().max(5) accepts strings whose length is at most five and rejects longer values. The method is chainable, so additional string checks can follow it.
Follow-up: How can the validation error be customized? Pass the supported error configuration as the second argument, for example z.string().max(5, { error: "Too long" }).
QWhich other Zod schemas expose .max()?
The method is not limited to strings. The documentation shows .max() for arrays, dates, bigints, and files, with the constrained quantity depending on the schema type.
Follow-up: What is the array equivalent of a maximum string length? Use z.array(elementSchema).max(n) to allow no more than n items.
Related
z.string().min()z.string().length()z.array().max()z.date().max()z.bigint().lte()fileSchema.max()