JavaScript Temporal PlainTime
The PlainTime Object
The Temporal.PlainTime object is a time object without a date.
It represents an ISO 8601 wall-clock time without a date or time zone.
Example: 10:30:00.
It is useful for opening hours, alarms, and any time-only values.
The Temporal.PlainTime Object
The Temporal PlainTime object is a time object with no date.
It represents an ISO 8601 wall-clock time without a date or time zone.
Example: 14:30:00.
Create a PlainTime
You can create a PlainTime from a string.
You can also create a PlainTime using numeric values.
Note
The parameters are: hour, minute, second, millisecond, microsecond, nanosecond.
Get the Current Time
You can get the current local time using Temporal.Now.plainTimeISO().
Get Time Parts
You can read the different parts of a PlainTime value.
Add and Subtract Time
Use add() and subtract() to do time math.
PlainTime is immutable, so the original value is not changed.
Example
const time = Temporal.PlainTime.from("14:30");
const later = time.add({ minutes: 45 });
const earlier = time.subtract({ hours: 2 });
Try it Yourself »
If the time passes midnight, it wraps around:
Example
const time = Temporal.PlainTime.from("23:30");
const result = time.add({ minutes: 90 });
Try it Yourself »
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.PlainTime.from("09:00");
const end = Temporal.PlainTime.from("17:30");
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.
Compare PlainTime Values
Use Temporal.PlainTime.compare() to compare times.
Example
// Create two PlainTime objects
const a = Temporal.PlainTime.from("08:30");
const b = Temporal.PlainTime.from("14:30");
// Compare the two objects
result = Temporal.PlainTime.compare(a, b));
Try it Yourself »
The result is:
- -1 if the first time is earlier
- 0 if they are equal
- 1 if the first time is later
Note
Do not use =, <, or > when comparing temporal time.
Equal PlainTime Values
Use equals() to check if two times are the same.
Example
// Create two PlainTime objects
const a = Temporal.PlainTime.from("14:30");
const b = Temporal.PlainTime.from("14:30");
// Compare the two objects
result = a.equals(b);
Try it Yourself »
Calculate the Difference Between Two Times
Use until() or since() to calculate differences.
Examples
// Create two PlainTime objects
const start = Temporal.PlainTime.from("09:00");
const end = Temporal.PlainTime.from("17:30");
// Calculate the difference
const diff = start.until(end);
Try it Yourself »
// Create two PlainTime objects
const start = Temporal.PlainTime.from("09:00");
const end = Temporal.PlainTime.from("17:30");
// Calculate the difference
const diff = start.since(end);
Try it Yourself »
Note
The until() and since() methods return a
Temporal.Duration.
The Temporal.PlainTime object has 6 properties of time information.
When to Use PlainTime
Opening hours (for example: 09:00 to 17:00).
Alarm clock times.
Recurring daily schedules.
Time input fields (without date and time zone).
Note
If you need time zone support, use ZonedDateTime.
Summary
Temporal.PlainTime represents a time without date and time zone.
It is immutable, easy to compare, and useful for daily time values.
In the next chapter you will learn about PlainDateTime (a combo of PlainDate and PlainTime).
Temporal PlainTime Methods
| Constructing | Description |
|---|---|
| from() | Returns a new PlainTime object from another object or a string |
| Arithmetic | |
| add() | Returns a new PlainTime with a duration added |
| subtract() | Returns a new PlainTime with a duration subtracted |
| round() | Returns a new PlainTime rounded to a given unit |
| Comparing | |
| compare() | Returns -1, 0, or 1 from comparing two times |
| equals() | Returns true if two PlainTime objects are identical |
| since() | Returns the difference since another time |
| until() | Returns the difference until another time |
| Converting | |
| with() | Returns a new PlainTime with specified fields modified |
| Formatting | |
| toString() | Returns an RFC 9557 format string representation |
| toJSON() | Returns an RFC 9557 format string for JSON serialization |
| toLocaleString() | Returns a language-sensitive representation of the time |
| valueOf() | Throws a TypeError (prevents temporals from being converted to primitives) |
Temporal.PlainTime Properties
| Property | Description |
|---|---|
| hour | The hour as an integer (0-23 |
| microsecond | The microsecond as an integer (0-999) |
| millisecond | The millisecond as an integer (0-999) |
| minute | The minute as an integer (0-59) |
| nanosecond | The nanosecond as an integer (0-999) |
| second | The second as an integer (0-59) |
