JavaScript Temporal PlainDate
The Temporal.PlainDate Object
The Temporal.PlainDate object represents a calendar date without time or timezone.
A Temporal.PlainDate is typically in ISO 8601 format ("2026-05-01").
It is immutable, easy to compare, and safer than using Date for date-only values.
It is used for dates that remain the same regardless of time zone, such as birthdays or holidays.
Dates with No Time
What You Will Learn:
- How to use JavaScript Temporal.PlainDate
- How to work with dates without time
- How to add and subtract days
- How to compare dates safely
Create a PlainDate
You can create a PlainDate from a string.
The Temporal.PlainDate.from() method creates a PlainDate object with no time zone:
The Temporal.PlainDate.from()method above:
- Parses the input using ISO 8601 parsing rules
- Accepts strings: "2026-05-01"
- Accepts objects: { year:2026, month:5, day:1 }
- Accepts temporal: PlainDate
- Returns a calendar date without a time like 2026-05-17.
Note
Parsing means validation pluss automatic conversion.
You can also create a PlainDate using year, month, and day values.
The Temporal.PlainDate() method creates a temporal PlainDate object with no time zone.
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 Date, months start at 1.
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
Get the Current Date
Use Temporal.Now.plainDateISO() to get today's date.
Add and Subtract Days
Use the add() method to add time.
This does not change the original date.
Example
let date = Temporal.PlainDate.from("2026-05-17");
let nextWeek = date.add({ days: 7 });
Try it Yourself »
Use the subtract() method to add time.
Example
let date = Temporal.PlainDate.from("2026-05-17");
let previousWeek = date.subtract({ days: 7 });
Try it Yourself »
Add Months or Years
You can add months or years safely.
Example
const date = Temporal.PlainDate.from("2026-05-17");
const nextMonth = date.add({ months: 1 });
Try it Yourself »
Note
Temporal handles month lengths automatically.
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);
Try it Yourself »
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 plain date with a different year, month, or day.
Example
// Create a Temporal object
const date = Temporal.PlainDate.from("2026-05-17");
// Replace month and day
const customDate = date.with({ month:12, day:25 });
Try it Yourself »
Compare Dates
The compare() method returns -1, 0 or 1.
- -1 if date1 is before date2
- 0 if equal
- 1 if after
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);
Try it Yourself »
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));
Try it Yourself »
Why < and > Do Not Work
Temporal objects are objects, not primitive numbers.
When you write (a < b), JavaScript tries to convert both objects to primitives.
For Temporal objects, this does not produce a numeric timestamp like Dates.
Example
// Create two Temporal objects
const a = Temporal.PlainDate.from("2026-02-17");
const b = Temporal.PlainDate.from("2026-03-01");
// Compare the dates
console.log(a < b); // ❌ Error
Temporal.PlainDate Properties
The Temporal.PlainDate object has 16 properties of calendar date information.
Temporal Calendars
new Temporal.PlainDate(...) defaults to ISO 8601.
If you want a specific calendar, you CAN add a calendrer parameter:
Example
new Temporal.PlainDate(2026, 5, 1, 'iso8601')
.from(...) defaults to ISO 8601.
You CANNOT add a calendar parameter, but if the input string includes a calendar, it is used:
Example
Temporal.PlainDate.from('2026-05-01[u-ca=iso8601]')
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 |
Note
A PlainDate object is essentially the date part of a Temporal.PlainDateTime object, with the time information removed.
