JavaScript Temporal Instant
The Temporal.Instant Object
A Temporal.Instant object represents an exact UTC moment in time.
Temporal.Instant has no time zone or calendar.
Temporal.Instant stores a count of nanoseconds since the Unix epoch: January 1, 1970 00.00.
It replaces Date timestamp usage and provides clearer and safer comparisons.
Learn how to use JavaScript Temporal.Instant to work with exact moments in time.
Compare Instants, convert from timestamps, and replace Date.now().
Note
Nanosecond precision is 1000 times higher than the millisecond precision of the old Date object.
Create an Instant
An Instant represents an exact moment in UTC time.
You can create an Instant from the current time:
This returns the exact current moment in UTC.
Create an Instant from a String
You can also create an Instant from an RFC 9557 string.
The Z at the end means UTC time.
Create an Instant from Epoch Milliseconds
You can create an Instant from a Unix timestamp (milliseconds since 1970-01-01).
This is similar to how Date works internally.
Creating an Instant:
| From | Code |
| String | Temporal.Instant.from('1969-07-20T20:17:00Z') |
| Current time | Temporal.Now.instant() |
| Epoch millisec | Temporal.Instant.fromEpochMilliseconds() |
| Epoch nanosec | Temporal.Instant.fromEpochNanoseconds() |
Replace Date.now()
With Date, you often use Date.now() to get the current timestamp.
With Temporal, you can use:
Temporal Example
const instant = Temporal.Now.instant();
let timestamp = instant.epochMilliseconds;
Try it Yourself »
The property epochMilliseconds returns the timestamp value.
Convert Instant to Date and Time
An Instant does not include time zone information.
You must convert it to a ZonedDateTime to display local time.
Example
const instant = Temporal.Now.instant();
const zoned = instant.toZonedDateTimeISO("Europe/Oslo");
Try it Yourself »
This converts the UTC moment to a specific time zone.
When to Use Instant
When storing timestamps in a database.
When comparing exact moments in time.
When working with logs or events.
When you need a UTC-based value.
Use Instant when you care about the exact moment, not how it looks in a time zone.
Temporal.Instant Methods
| Method | Description |
|---|---|
| from() | Returns a new Instant object from another object or a string |
| fromEpochMilliseconds() | Returns a new Instant object from a number of milliseconds |
| fromEpochNanoseconds() | Returns a new Instant object from a number of nanoseconds |
| toZonedDateTimeISO() | Returns a new ZonedDatetime object |
| Arithmetic | |
| add() | Returns a new Instant with a duration added |
| subtract() | Returns a new Instant with a duration subtracted |
| Comparison | |
| compare() | Returns -1, 0, or 1 from comparing two dates |
| equals() | Returns true if two Instant objects are identical |
| since() | Returns the difference since another date |
| until() | Returns the difference until another date |
| 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 (prevents temporals from being converted to primitives) |
