Skip to main content

​
Basic Usage

import { z } from 'zod';

const schema = z.string();
schema.parse("hello"); // "hello"
schema.parse(123); // throws ZodError

​
Type Signature

function string(params?: string | $ZodStringParams): ZodString
​
params
string | $ZodStringParams
Optional error message (string) or configuration object

​
Validation Methods

​
Length Validations

​
.min()

Enforces minimum string length. 
const schema = z.string().min(5);
schema.parse("hello"); // "hello"
schema.parse("hi"); // throws
​
minLength
number
required
Minimum length of the string
​
params
string | $ZodCheckMinLengthParams
Custom error message or params object with message property

​
.max()

Enforces maximum string length. 
const schema = z.string().max(5);
schema.parse("hello"); // "hello"
schema.parse("hello world"); // throws
​
maxLength
number
required
Maximum length of the string
​
params
string | $ZodCheckMaxLengthParams
Custom error message or params object

​
.length()

Enforces exact string length. 
const schema = z.string().length(5);
schema.parse("hello"); // "hello"
schema.parse("hi"); // throws
​
len
number
required
Exact length required
​
params
string | $ZodCheckLengthEqualsParams
Custom error message or params object

​
.nonempty()

Requires at least one character. Equivalent to .min(1). 
const schema = z.string().nonempty();
schema.parse("hello"); // "hello"
schema.parse(""); // throws
​
params
string | $ZodCheckMinLengthParams
Custom error message

​
Content Validations

​
.regex()

Validates string against a regular expression. 
const schema = z.string().regex(/^[0-9]+$/);
schema.parse("12345"); // "12345"
schema.parse("hello"); // throws
​
regex
RegExp
required
Regular expression pattern to match
​
params
string | $ZodCheckRegexParams
Custom error message or params object

​
.includes()

Requires string to contain a substring. 
const schema = z.string().includes("hello");
schema.parse("hello world"); // "hello world"
schema.parse("goodbye"); // throws

// With position
const schema2 = z.string().includes("world", { position: 6 });
schema2.parse("hello world"); // "hello world"
schema2.parse("world hello"); // throws (position < 6)
​
value
string
required
Substring that must be present
​
params
string | $ZodCheckIncludesParams
Custom error message or params object with optional position property

​
.startsWith()

Requires string to start with a specific prefix. 
const schema = z.string().startsWith("https://");
schema.parse("https://example.com"); // "https://example.com"
schema.parse("http://example.com"); // throws
​
value
string
required
Required prefix
​
params
string | $ZodCheckStartsWithParams
Custom error message

​
.endsWith()

Requires string to end with a specific suffix. 
const schema = z.string().endsWith(".com");
schema.parse("example.com"); // "example.com"
schema.parse("example.org"); // throws
​
value
string
required
Required suffix
​
params
string | $ZodCheckEndsWithParams
Custom error message

​
Case Validations

​
.lowercase()

Validates that string contains only lowercase characters. 
const schema = z.string().lowercase();
schema.parse("hello"); // "hello"
schema.parse("Hello"); // throws
​
params
string | $ZodCheckLowerCaseParams
Custom error message

​
.uppercase()

Validates that string contains only uppercase characters. 
const schema = z.string().uppercase();
schema.parse("HELLO"); // "HELLO"
schema.parse("hello"); // throws
​
params
string | $ZodCheckUpperCaseParams
Custom error message

​
Transform Methods

Transform methods modify the string value during parsing.

​
.trim()

Removes whitespace from both ends. 
const schema = z.string().trim();
schema.parse("  hello  "); // "hello"

​
.toLowerCase()

Converts string to lowercase. 
const schema = z.string().toLowerCase();
schema.parse("HELLO"); // "hello"

​
.toUpperCase()

Converts string to uppercase. 
const schema = z.string().toUpperCase();
schema.parse("hello"); // "HELLO"

​
.normalize()

Normalizes the string using Unicode normalization. 
const schema = z.string().normalize();
const schema2 = z.string().normalize("NFC");
​
form
'NFC' | 'NFD' | 'NFKC' | 'NFKD' | (string & {})
Unicode normalization form (default: “NFC”)

​
.slugify()

Converts string to URL-friendly slug format. 
const schema = z.string().slugify();
schema.parse("Hello World!"); // "hello-world"

​
Properties

​
.format

Returns the format string if the schema has a specific format, or null. 
const schema = z.string().email();
schema.format; // "email"

const plain = z.string();
plain.format; // null

​
.minLength

Returns the minimum length constraint, or null if not set. 
const schema = z.string().min(5);
schema.minLength; // 5

​
.maxLength

Returns the maximum length constraint, or null if not set. 
const schema = z.string().max(10);
schema.maxLength; // 10

​
Deprecated Format Methods

The following methods are deprecated in favor of standalone format schemas:
  • .email() - Use z.email() instead
  • .url() - Use z.url() instead
  • .uuid() - Use z.uuid() instead
  • .guid() - Use z.guid() instead
  • .cuid() - Use z.cuid() instead
  • .cuid2() - Use z.cuid2() instead
  • .ulid() - Use z.ulid() instead
  • .nanoid() - Use z.nanoid() instead
  • .jwt() - Use z.jwt() instead
  • .base64() - Use z.base64() instead
  • .base64url() - Use z.base64url() instead
  • .emoji() - Use z.emoji() instead
  • .ipv4() - Use z.ipv4() instead
  • .ipv6() - Use z.ipv6() instead
  • .datetime() - Use z.iso.datetime() instead
  • .date() - Use z.iso.date() instead
  • .time() - Use z.iso.time() instead

​
Chaining

All validation and transform methods return this, enabling method chaining: 
const schema = z.string()
  .min(5)
  .max(100)
  .trim()
  .toLowerCase()
  .startsWith("hello");

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us