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.
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 PlainTime
Use add() and subtract()
to do PlainTime 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 »
Calculate PlainTime Differences
Use since() and until()
to calculate PlainTime differences.
Both methods return a Temporal.Duration object.
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.since(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.until(end);
Try it Yourself »
JavaScript since() and until()
All temporal date objects have their own since() method:
- plaindate.since(plaindate)
- plaintime.since(plaintime)
- plainyearmonth.since(plainyearmonth)
- plainmonthday.since(plainmonthday)
- plaindatetime.since(plaindatetime)
- zoneddatetime.since(zoneddatetime)
- instant.since(instant)
All temporal objects have their own until() method:
- plaindate.until(plaindate)
- plaintime.until(plaintime)
- plainyearmonth.until(plainyearmonth)
- plainmonthday.until(plainmonthday)
- plaindatetime.until(plaindatetime)
- zoneddatetime.until(zoneddatetime)
- instant.until(instant)
LearnMore:
The PlainTime compare() Method
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
Do not use =, <, or > when comparing temporal time.
All temporal objects have their own compare() method:
- Temporal.Instant.compare(instant1, instant2)
- Temporal.PlainDate.compare(plaindate1, plaindate2)
- Temporal.PlainTime.compare(plaintime1, plaintime2)
- Temporal.PlainYearMonth.compare(plainyearmonth1, plainyearmonth2)
- Temporal.PlainMonthDay.compare(plainmonthday1 plainmonthday2)
- Temporal.PlainDateTime.compare(plaindatetime1,plaindatetime2)
- Temporal.ZonedDateTime.compare(zoneddtatime1, zoneddtatime2)
- Temporal.Duration.compare(duration1, duration2)
LearnMore:
The PlainTime equals() Method
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 »
Most (*) temporal objects have their own equals() method:
- instant.equals(instant)
- plaindate.equals(plaindate)
- plaintime.equals(plaintime)
- plainyearmonth.equals(plainyearmonth)
- plainmonthday.equals(plainmonthday)
- plaindateTime.equals(plaindatetime)
- zoneddateTime.equals(zoneddtatime)
(*) Duration has not.
LearnMore:
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).
If you need date, use PlaneDateTime.
Temporal PlainTime Methods
| Constructing | Description |
|---|---|
| from() | Creates a new PlainTime object from an object or a string |
| new | Creates a new PlainTime object from integer parameters |
| 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 |
| Modifying | |
| with() | Returns a new PlainTime with specified fields modified |
| Formatting | |
| toJSON() | Returns an RFC 9557 format string for JSON serialization |
| toLocaleString() | Returns a language-sensitive representation of the time |
| toString() | Returns an RFC 9557 format representation of the time |
| valueOf() | Throws a TypeError Prevents temporals from being converted to primitives |
Temporal.PlainTime Properties
The Temporal.PlainTime object has 6 properties of time information.
| 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) |
