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:
| From | Code |
|---|---|
| Constructor (new) | new Temporal.PlainDate() |
| ISO String | Temporal.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
// 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
// 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
// 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?
- You have trusted numeric values
- You want speed
- You want predictable construction
- You are doing date math
- You are handling user input (strings)
- You are handling external data (JSON)
- You want maximum flexibility
- 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 )
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;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
)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);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:
new Temporal.PlainDate(2026, 5, 17, "gregory")The from() method supports calendars using the [u-ca=calendar] syntax or a calendar property in objects.
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:
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
| Constructing | Description |
|---|---|
| from() | Creates a new PlainDate object from an object or a string |
| new | Creates 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
| Property | Description |
|---|---|
| calendarID | Calendar system identifier ("iso8601") |
| day | The day as an integer (1-31) |
| dayOfWeek | The day of the week as an integer (1 = Monday) |
| dayOfYear | The ordinal day of the year |
| daysInMonth | The total number of days in that month |
| daysInWeek | The total number of days in that week |
| daysInYear | The total number of days in that year |
| era | The era name of the calendar, if applicable |
| eraYear | The year within the era, if applicable |
| inLeapYear | A boolean indicating if the year is a leap year |
| month | The month as an integer (1-12) |
| monthCode | A string code for the month ("M01") |
| monthsInYear | The total number of months in that year |
| weekOfYear | The week number within the year |
| year | The year as an integer |
| yearOfWeek | The year that the week belongs to |
Display All Properties
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.