Temporal PlainDate

The Temporal.PlainDate Object

The Temporal.PlainDate object represents a calendar date without a time.

A Temporal.PlainDate is typically in ISO 8601 format (2026-05-01).

It is easier to use and safer to compare than DateTime objects for dates that are the same regardless of time zone, such as birthdays and holidays.

How to Create a PlainDate Object

An PlainDateTime object can be created in several different ways:

Create a PlainDate with new

You can create a PlainDate object using the new constructor.

The constructor takes year, month, and day parameters.

Example

// Create a PlainDate object

const date = new Temporal.PlainDate(2026, 5, 17);

The Temporal.PlainDate() method above:

• Uses a constructor call
• Expects numeric arguments (year, month, day).
• Returns a calendar date without a time like 2026-05-17.

Note: Unlike JavaScript Date, Temporal months start at 1.

Create a PlainDate from a String

You can create a PlainDate object from an ISO 8601 / RFC 9557 string.

Example

// Create a PlainDate object

const date = Temporal.PlainDate.from("2026-05-17");

In the example above:

• The input is parsed using ISO 8601 parsing rules
• ISO 8601 accepts strings like "2026-05-01"

Note: Parsing means validation pluss automatic conversion.

Create a PlainDate from an Object

You can create a PlainDate object from an object.

Example

// Create a PlainDate object

const date = Temporal.PlainDate.from({year:2026, month:5, day:1});

From the example above, you can reason that the from() method can accept both object literals and PlainDate objects.

Example

// Create a PlainDate object

const d1 = Temporal.PlainDate.from({year:2026, month:5, day:1});

// Create another PlainDate object

const d2 = Temporal.PlainDate.from(d1);

Create a PlainDate Object from Now

The Temporal.Now object has a method for getting the current date:

Example

let today = Temporal.Now.plainDateISO();

The Temporal.Now.plainDateISO() method is used to get the current date.

It returns a PlainDate object with the (year, month, day) in the ISO 8601 calendar, specifically ignoring time zones and times.

When to Use Which?

Use new Temporal.PlainDate() when:

• You have trusted numeric values
• You want speed
• You want predictable construction
• You are doing date math

Use Temporal.PlainDate.from() when:

• You are handling user input (strings)
• You are handling external data (JSON)
• You want maximum flexibility

Use Temporal.Now.plainDateISO() when:

• You you need the current date

Add and Subtract Days

Use the add() method to add time.

Example

let date = Temporal.PlainDate.from("2026-05-17");

let nextWeek = date.add({ days: 7 });

Use the subtract() method to subtract time.

Example

let date = Temporal.PlainDate.from("2026-05-17");

let previousWeek = date.subtract({ days: 7 });

All temporal objects have their own add() method:

• duration.add(duration)
• instant.add(duration)
• plaindate.add(duration)
• plaintime.add(duration)
• plainyearmonth.add(duration)
• plainmonthday.add(duration)
• plaindatetime.add(duration)
• zoneddatetime.add(duration)

All temporal objects have their own subtract() method:

• duration.subtract(duration)
• instant.subtract(duration)
• plaindate.subtract(duration)
• plaintime.subtract(duration)
• plainyearmonth.subtract(duration)
• plainmonthday.subtract(duration)
• plaindatetime.subtract(duration)
• zoneddatetime.subtract(duration)

Note: Learn More: JavaScript Temporal Arithmetic

Duration vs Date Math

With JavaScript Date, you must often calculate time differences manually using milliseconds.

Date Example

const start = new Date("2026-05-01");

const end = new Date("2026-05-17");

let diff = end - start;

Note: Temporal provides methods that are clearer and safer than using JavaScript Date methods.

JavaScript Temporal since()

The since() method calculates the duration between two temporal dates.

Syntax

t1.since(t2, options)

Note: Meaning: At time t1, how much time has passed since time t2?

Example

const start = Temporal.PlainDate.from("2026-05-01");

const end = Temporal.PlainDate.from("2026-05-17");

const duration = end.since(start);

Note: The since() method returns a Temporal.Duration Object representing the elapsed time. The duration is positive if the "other" date is in the past. The duration is negative if the "other" date is in the future.

The with() Method

The with() method creates a new PlainDate object with specific field replaced.

Example

// Create a PlainDate object

const date = Temporal.PlainDate.from("2026-05-17");

// Replace month and day

const customDate = date.with({ month:12, day:25 });

Compare Dates

The compare(date1, date2) method returns -1, 0 or 1:

• -1 if date1 is before date2
• 0 they are if equal
• 1 if date 1 is after date2

Example

// Create two Temporal objects

const date1 = Temporal.PlainDate.from("2026-02-17");

const date2 = Temporal.PlainDate.from("2026-03-01");

// Compare the dates

let result = Temporal.PlainDate.compare(date1, date2);

You can also use equals() to check if two dates are the same.

Example

// Create two Temporal objects

const a = Temporal.PlainDate.from("2026-02-17");

const b = Temporal.PlainDate.from("2026-02-17");

// Compare the dates

let result = (a.equals(b));

Temporal.PlainDate Properties

The Temporal.PlainDate object has 16 properties of calendar date information.

Example

const time = new Temporal.PlainDate(2026, 5, 17);

Temporal Calendars

Temporal.PlainDate defaults to the ISO 8601 calendar.

If you want a specific calendar, you can add a calender parameter:

Example

new Temporal.PlainDate(2026, 5, 17, "gregory")

The from() method supports calendars using the [u-ca=calendar] syntax or a calendar property in objects.

Examples

Temporal.PlainDate.from("2026-05-17[u-ca=chinese]")

Valid calendar identifiers (calendar_id) for Temporal objects:

• iso8601 - Default ISO calendar
• gregory - Gregorian calendar
• buddhist - Buddhist calendar
• chinese - Chinese calendar
• coptic - Coptic calendar
• dangi - Korean Dangi calendar
• ethioaa - Ethiopic Amete Alem
• ethiopic - Ethiopic calendar
• hebrew - Hebrew calendar
• indian - Indian (Saka) calendar
• islamic - Islamic calendar
• islamic-civil - Islamic civil calendar
• islamic-rgsa - Islamic (Saudi Arabia)
• islamic-tbla - Islamic tabular calendar
• islamic-umalqura - Umm al-Qura calendar
• japanese - Japanese imperial calendar
• persian - Persian (Solar Hijri) calendar
• roc - Republic of China calendar

You can list supported values in your environment with:

Example

Intl.supportedValuesOf("calendar");

When to Use PlainDate

• Any date without time
• Birthdays
• Deadlines
• Holidays
• Booking dates

Replace Date for Date-Only Values

With Date, you always get a time and time zone.

This can create confusion when you only need a calendar date.

Date Example

let d = new Date("2026-05-17");

PlainDate avoids this by storing only year, month, and day.

Temporal.PlainDate Methods

Temporal.PlainDate Properties

Display All Properties

const date = new Temporal.PlainDate(2026, 5, 17);

Note: A PlainDate object is essentially the date part of a Temporal.PlainDateTime object, with the time information removed.