z.bigint()

BigInt schema type with validations

Basic Usage

import { z } from 'zod';

const schema = z.bigint();
schema.parse(BigInt(42)); // 42n
schema.parse(42n); // 42n
schema.parse(42); // throws ZodError
schema.parse("42"); // throws ZodError

Type Signature

function bigint(params?: string | $ZodBigIntParams): ZodBigInt

params · string | $ZodBigIntParams

Optional error message (string) or configuration object

Comparison Methods

.gt()

Greater than (exclusive).

const schema = z.bigint().gt(BigInt(5));
schema.parse(6n); // 6n
schema.parse(5n); // throws

value · bigint · required

Exclusive minimum value

params · string | $ZodCheckGreaterThanParams

Custom error message

.gte() / .min()

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

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

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

value · bigint · required

Inclusive minimum value

params · string | $ZodCheckGreaterThanParams

Custom error message

.lt()

Less than (exclusive).

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

value · bigint · 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.bigint().lte(5n);
schema.parse(5n); // 5n
schema.parse(4n); // 4n
schema.parse(6n); // throws

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

value · bigint · required

Inclusive maximum value

params · string | $ZodCheckLessThanParams

Custom error message

Sign Validations

.positive()

Requires bigint to be greater than zero.

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

params · string | $ZodCheckGreaterThanParams

Custom error message

.negative()

Requires bigint to be less than zero.

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

params · string | $ZodCheckLessThanParams

Custom error message

.nonnegative()

Requires bigint to be greater than or equal to zero.

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

params · string | $ZodCheckGreaterThanParams

Custom error message

.nonpositive()

Requires bigint to be less than or equal to zero.

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

params · string | $ZodCheckLessThanParams

Custom error message

Multiple Of

.multipleOf()

Requires bigint to be a multiple of a given value.

const schema = z.bigint().multipleOf(5n);
schema.parse(15n); // 15n
schema.parse(-15n); // -15n
schema.parse(13n); // throws

value · bigint · required

The divisor

params · string | $ZodCheckMultipleOfParams

Custom error message

Properties

.minValue

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

z.bigint().minValue; // null
z.bigint().min(5n).minValue; // 5n
z.bigint().gte(5n).minValue; // 5n
z.bigint().nonnegative().minValue; // 0n

.maxValue

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

z.bigint().maxValue; // null
z.bigint().max(5n).maxValue; // 5n
z.bigint().lte(5n).maxValue; // 5n
z.bigint().nonpositive().maxValue; // 0n

.format

Returns the format string if set, or null.

z.bigint().format; // null
z.int64().format; // "int64"
z.uint64().format; // "uint64"

Specialized BigInt Formats

Use these for specific 64-bit integer types:

z.int64()

Signed 64-bit integer.

import { z } from 'zod';

const schema = z.int64();
schema.parse(9223372036854775807n); // max int64

params · string | $ZodBigIntFormatParams

Optional error message

z.uint64()

Unsigned 64-bit integer.

import { z } from 'zod';

const schema = z.uint64();
schema.parse(18446744073709551615n); // max uint64
schema.parse(-1n); // throws

params · string | $ZodBigIntFormatParams

Optional error message

Use Cases

BigInt is useful for:

• Large integers beyond Number.MAX_SAFE_INTEGER (2^53 - 1)
• Precise integer arithmetic
• Cryptographic operations
• Working with blockchain/cryptocurrency values
• Database IDs (e.g., Twitter snowflake IDs)

// Twitter snowflake IDs
const tweetId = z.bigint().positive();

// Cryptocurrency amounts (e.g., wei in Ethereum)
const weiAmount = z.bigint().nonnegative();

// Large database counters
const counter = z.bigint().min(0n);

Chaining

All methods return this, enabling chaining:

const schema = z.bigint()
  .min(0n)
  .max(1000000n)
  .multipleOf(100n);

TypeScript Type

import { z } from 'zod';

const schema = z.bigint();
type BigIntType = z.infer<typeof schema>; // bigint

See Also

• z.number() - For numbers within safe integer range
• z.int64() - Signed 64-bit integers
• z.uint64() - Unsigned 64-bit integers