z.string()

String schema type with validation methods

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

• String Formats - Specialized string format schemas
• Transforms - General transformation methods
• Custom Validations - Using .refine() for custom logic