z.number()

Number schema type with numeric validations

Basic Usage

import { z } from 'zod';

const schema = z.number();
schema.parse(42); // 42
schema.parse(3.14); // 3.14
schema.parse("42"); // throws ZodError

Type Signature

function number(params?: string | $ZodNumberParams): ZodNumber

params · string | $ZodNumberParams

Optional error message (string) or configuration object

Important: NaN and Infinity

In Zod v4, z.number() does NOT accept NaN or Infinity by default:

const schema = z.number();
schema.parse(Number.NaN); // throws
schema.parse(Number.POSITIVE_INFINITY); // throws
schema.parse(Number.NEGATIVE_INFINITY); // throws

Comparison Methods

.gt()

Greater than (exclusive).

const schema = z.number().gt(5);
schema.parse(6); // 6
schema.parse(5); // throws

value · number · required

Exclusive minimum value

params · string | $ZodCheckGreaterThanParams

Custom error message or params object

.gte() / .min()

Greater than or equal (inclusive). .min() is an alias for .gte().

const schema = z.number().gte(5);
schema.parse(5); // 5
schema.parse(6); // 6
schema.parse(4); // throws

// Equivalent
const schema2 = z.number().min(5);

value · number · required

Inclusive minimum value

params · string | $ZodCheckGreaterThanParams

Custom error message

.lt()

Less than (exclusive).

const schema = z.number().lt(5);
schema.parse(4); // 4
schema.parse(5); // throws

value · number · required

Exclusive maximum value

params · string | $ZodCheckLessThanParams

Custom error message

.lte() / .max()

Less than or equal (inclusive). .max() is an alias for .lte().

const schema = z.number().lte(5);
schema.parse(5); // 5
schema.parse(4); // 4
schema.parse(6); // throws

// Equivalent
const schema2 = z.number().max(5);

value · number · required

Inclusive maximum value

params · string | $ZodCheckLessThanParams

Custom error message

Sign Validations

.positive()

Requires number to be greater than zero.

const schema = z.number().positive();
schema.parse(1); // 1
schema.parse(0); // throws
schema.parse(-1); // throws

params · string | $ZodCheckGreaterThanParams

Custom error message

.negative()

Requires number to be less than zero.

const schema = z.number().negative();
schema.parse(-1); // -1
schema.parse(0); // throws
schema.parse(1); // throws

params · string | $ZodCheckLessThanParams

Custom error message

.nonnegative()

Requires number to be greater than or equal to zero.

const schema = z.number().nonnegative();
schema.parse(0); // 0
schema.parse(1); // 1
schema.parse(-1); // throws

params · string | $ZodCheckGreaterThanParams

Custom error message

.nonpositive()

Requires number to be less than or equal to zero.

const schema = z.number().nonpositive();
schema.parse(0); // 0
schema.parse(-1); // -1
schema.parse(1); // throws

params · string | $ZodCheckLessThanParams

Custom error message

Format Validations

.int() (Legacy)

Requires an integer value. Accepts only safe integers (Number.MIN_SAFE_INTEGER to Number.MAX_SAFE_INTEGER).

const schema = z.number().int();
schema.parse(42); // 42
schema.parse(3.14); // throws

Consider using z.int() instead for a cleaner API.

params · string | $ZodCheckNumberFormatParams

Custom error message

.safe() (Deprecated)

Identical to .int(). Only accepts safe integers.

const schema = z.number().safe();
schema.parse(Number.MAX_SAFE_INTEGER); // valid
schema.parse(Number.MAX_SAFE_INTEGER + 1); // throws

.finite() (Deprecated)

In v4, this is a no-op since z.number() doesn’t accept infinite values by default.

const schema = z.number().finite();
// This is the same as z.number()

Multiple Of

.multipleOf() / .step()

Requires number to be a multiple of a given value. .step() is an alias.

const schema = z.number().multipleOf(5);
schema.parse(15); // 15
schema.parse(-15); // -15
schema.parse(7.5); // throws

// Precision example
const precise = z.number().multipleOf(0.01);
precise.parse(1.23); // 1.23
precise.parse(1.234); // throws

value · number · required

The divisor (can be positive or negative)

params · string | $ZodCheckMultipleOfParams

Custom error message

Properties

.minValue

Returns the minimum value constraint, or null if not set.

z.number().minValue; // null
z.number().min(5).minValue; // 5
z.number().gte(5).minValue; // 5
z.number().gt(5).minValue; // 5
z.number().positive().minValue; // 0
z.number().nonnegative().minValue; // 0

.maxValue

Returns the maximum value constraint, or null if not set.

z.number().maxValue; // null
z.number().max(5).maxValue; // 5
z.number().lte(5).maxValue; // 5
z.number().lt(5).maxValue; // 5
z.number().negative().maxValue; // 0
z.number().nonpositive().maxValue; // 0

.isInt

Returns true if the schema requires an integer.

z.number().isInt; // false
z.number().int().isInt; // true
z.number().safe().isInt; // true
z.number().multipleOf(5).isInt; // true

.isFinite

Always returns true in Zod v4 (numbers don’t accept infinite values).

z.number().isFinite; // true

.format

Returns the format string if set, or null.

z.number().format; // null
z.int().format; // "int"
z.int32().format; // "int32"

Specialized Number Formats

Use these standalone constructors instead of methods on z.number():

• z.int() - Safe integer
• z.int32() - 32-bit signed integer
• z.uint32() - 32-bit unsigned integer
• z.float32() - 32-bit float
• z.float64() - 64-bit float (standard JavaScript number)

import { z } from 'zod';

const age = z.int().min(0).max(120);
const temperature = z.float32();

Chaining

All methods return this, enabling chaining:

const schema = z.number()
  .min(0)
  .max(100)
  .int()
  .positive();

See Also

• z.int() - Integer type
• Number Formats - Specialized numeric types
• z.bigint() - For integers outside safe range