z.date()

Date schema type with temporal validations

Basic Usage

import { z } from 'zod';

const schema = z.date();
schema.parse(new Date()); // Date object
schema.parse("2023-01-01"); // throws ZodError
schema.parse(1234567890); // throws ZodError

Type Signature

function date(params?: string | $ZodDateParams): ZodDate

params · string | $ZodDateParams

Optional error message (string) or configuration object

Behavior

z.date() only accepts JavaScript Date objects. It does NOT accept:

• Timestamps (numbers)
• Date strings
• Other date representations

const schema = z.date();

// Valid
schema.parse(new Date()); // Date
schema.parse(new Date("2023-01-01")); // Date

// Invalid - throws ZodError
schema.parse("2023-01-01");
schema.parse(1234567890);
schema.parse(Date.now());

Validation Methods

.min()

Enforces a minimum date/time.

const schema = z.date().min(new Date("2023-01-01"));

schema.parse(new Date("2023-06-01")); // valid
schema.parse(new Date("2022-01-01")); // throws

// Can also use timestamp
const schema2 = z.date().min(Date.UTC(2023, 0, 1));

value · number | Date · required

Minimum date (as Date object or timestamp)

params · string | $ZodCheckGreaterThanParams

Custom error message

.max()

Enforces a maximum date/time.

const schema = z.date().max(new Date("2023-12-31"));

schema.parse(new Date("2023-06-01")); // valid
schema.parse(new Date("2024-01-01")); // throws

// Can also use timestamp
const schema2 = z.date().max(Date.UTC(2023, 11, 31));

value · number | Date · required

Maximum date (as Date object or timestamp)

params · string | $ZodCheckLessThanParams

Custom error message

Properties

.minDate (Deprecated)

Returns the minimum date constraint as a Date object, or null if not set.

const schema = z.date().min(new Date("2023-01-01"));
schema.minDate; // Date object for 2023-01-01

This property is deprecated. Check constraints directly in your code instead.

.maxDate (Deprecated)

Returns the maximum date constraint as a Date object, or null if not set.

const schema = z.date().max(new Date("2023-12-31"));
schema.maxDate; // Date object for 2023-12-31

This property is deprecated. Check constraints directly in your code instead.

Common Use Cases

Date Range Validation

const eventDate = z.date()
  .min(new Date("2024-01-01"))
  .max(new Date("2024-12-31"));

Future Dates Only

const futureDate = z.date().min(new Date());

futureDate.parse(new Date(Date.now() + 86400000)); // tomorrow - valid
futureDate.parse(new Date(Date.now() - 86400000)); // yesterday - throws

Past Dates Only

const pastDate = z.date().max(new Date());

pastDate.parse(new Date(Date.now() - 86400000)); // yesterday - valid
pastDate.parse(new Date(Date.now() + 86400000)); // tomorrow - throws

Birth Date Validation

const birthDate = z.date()
  .min(new Date("1900-01-01"))
  .max(new Date()); // not in the future

Type Coercion

To accept date strings or timestamps and convert them to Date objects:

import { z } from 'zod';

const schema = z.coerce.date();

schema.parse("2023-01-01"); // Date object
schema.parse(1672531200000); // Date object
schema.parse(new Date()); // Date object

Preprocessing

For custom date parsing logic:

import { z } from 'zod';

const dateFromString = z.preprocess(
  (arg) => {
    if (typeof arg === "string") {
      return new Date(arg);
    }
    return arg;
  },
  z.date()
);

dateFromString.parse("2023-01-01"); // Date object

ISO Date Strings

For validating ISO 8601 date strings, use the ISO schemas:

import { z } from 'zod';

// ISO date string (YYYY-MM-DD)
const isoDate = z.iso.date();
isoDate.parse("2023-01-01"); // "2023-01-01"

// ISO datetime string
const isoDateTime = z.iso.datetime();
isoDateTime.parse("2023-01-01T12:00:00Z"); // valid

// ISO time string
const isoTime = z.iso.time();
isoTime.parse("12:00:00"); // "12:00:00"

Refinements

For complex date logic:

// Only weekdays
const weekdayDate = z.date().refine(
  (date) => {
    const day = date.getDay();
    return day !== 0 && day !== 6; // not Sunday or Saturday
  },
  { message: "Date must be a weekday" }
);

// Business hours
const businessHours = z.date().refine(
  (date) => {
    const hour = date.getHours();
    return hour >= 9 && hour < 17;
  },
  { message: "Time must be during business hours (9am-5pm)" }
);

Chaining

const schema = z.date()
  .min(new Date("2020-01-01"))
  .max(new Date("2030-12-31"));

TypeScript Type

import { z } from 'zod';

const schema = z.date();
type DateType = z.infer<typeof schema>; // Date

See Also

• z.iso.date() - ISO 8601 date strings
• z.iso.datetime() - ISO 8601 datetime strings
• z.iso.time() - ISO 8601 time strings
• z.coerce.date() - Date with type coercion
• Refinements - Custom validation logic