Ejaz Ahmad
Digital Assets & Tools
Try Playground
Free ResourcesUI/UX ComponentsNewOnline ToolsWeb UtilitiesHostingTutorials & LMSNewPlaygrounds7 Live
Open Playground
← JavaScript PlainDateTimeJavaScript PlainYearMonth →
JS TutorialLesson #201

JavaScript Temporal PlainDate

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

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:

FromCode
Constructor (new)new Temporal.PlainDate()
ISO StringTemporal.PlainDate.from()
Now (current time)Temporal.Now.plainDateISO()

Create a PlainDate with new

You can create a PlainDate object using the new constructor.

The constructor takes year, month, and day parameters.

Example

Example Code

javascript
Try it Yourself
// 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.
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

Example Code

javascript
Try it Yourself
// 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"
Parsing means validation pluss automatic conversion.

Create a PlainDate from an Object

You can create a PlainDate object from an object.

Example

Example Code

javascript
Try it Yourself
// 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

Example Code

javascript
Try it Yourself
// 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

Example Code

javascript
Try it Yourself
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

Example Code

javascript
Try it Yourself
let date = Temporal.PlainDate.from("2026-05-17");

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

Use the subtract() method to subtract time.

Example

Example Code

javascript
Try it Yourself
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)
Learn More: > JavaScript Temporal Arithmetic

Duration vs Date Math

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

Date Example

Example Code

javascript
Try it Yourself
const start = new Date("2026-05-01");

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

let diff = end - start;
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

Example Code

javascript
Try it Yourself
t1.since(t2, options)
Meaning: > At time t1, how much time has passed since time t2?

Example

Example Code

javascript
Try it Yourself
const start = Temporal.PlainDate.from("2026-05-01");

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

const duration = end.since(start);
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

Example Code

javascript
Try it Yourself
// 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

Example Code

javascript
Try it Yourself
// 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

Example Code

javascript
Try it Yourself
// 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

Example Code

javascript
Try it Yourself
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

Example Code

javascript
Try it Yourself
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

Example Code

javascript
Try it Yourself
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

Example Code

javascript
Try it Yourself
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

Example Code

javascript
Try it Yourself
let d = new Date("2026-05-17");

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

Temporal.PlainDate Methods

ConstructingDescription
from()Creates a new PlainDate object from an object or a string
newCreates a new PlainDate object from (year, month, day)
Arithmetic
add()Returns a new PlainDate with a duration added
subtract()Returns a new PlainDate with a duration subtracted
Comparing
compare()Returns -1, 0, or 1 from comparing two dates
equals()Returns true if two PlainDate objects are identical
since()Returns the difference since another date
until()Returns the difference until another date
Converting
toPlainDateTime()Returns a new PlainDateTime object
toPlainMonthDay()Returns a new PlainMonthDay object
toPlainYearMonth()Returns a new PlainYearMonth object
toZonedDateTime()Returns a new ZonedDatetime object
with()Returns a new PlainDate with specified fields modified
withCalendar()Returns a new PlainDate with a different calendar system
Formatting
toJSON()Returns an RFC 9557 format string for JSON serialization
toLocaleString()Returns a language-sensitive representation of the date
toString()Returns an RFC 9557 format string representation
valueOf()Throws a TypeError (should not be converted to primitives)

Temporal.PlainDate Properties

PropertyDescription
calendarIDCalendar system identifier ("iso8601")
dayThe day as an integer (1-31)
dayOfWeekThe day of the week as an integer (1 = Monday)
dayOfYearThe ordinal day of the year
daysInMonthThe total number of days in that month
daysInWeekThe total number of days in that week
daysInYearThe total number of days in that year
eraThe era name of the calendar, if applicable
eraYearThe year within the era, if applicable
inLeapYearA boolean indicating if the year is a leap year
monthThe month as an integer (1-12)
monthCodeA string code for the month ("M01")
monthsInYearThe total number of months in that year
weekOfYearThe week number within the year
yearThe year as an integer
yearOfWeekThe year that the week belongs to

Display All Properties

Example Code

javascript
Try it Yourself
const date = new Temporal.PlainDate(2026, 5, 17);
A PlainDate object is essentially the date part of a Temporal.PlainDateTime object, > with the time information removed.

Interactive Code Examples

JS Example 1

javascript
Try it Yourself
JavaScript syntax and algorithm demonstration.
// Create a PlainDate object

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

JS Example 2

javascript
Try it Yourself
JavaScript syntax and algorithm demonstration.
// Create a PlainDate object

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

JS Example 3

javascript
Try it Yourself
JavaScript syntax and algorithm demonstration.
// Create a PlainDate object

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

JS Example 4

javascript
Try it Yourself
JavaScript syntax and algorithm demonstration.
// 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);

JS Example 5

javascript
Try it Yourself
JavaScript syntax and algorithm demonstration.
let today = Temporal.Now.plainDateISO();

JS Example 6

javascript
Try it Yourself
JavaScript syntax and algorithm demonstration.
let date = Temporal.PlainDate.from("2026-05-17");

let nextWeek = date.add({ days: 7 });
Previous: JavaScript PlainDateTimeNext: JavaScript PlainYearMonth