Date.prototype[Symbol.toPrimitive]()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

The [Symbol.toPrimitive]() method of Date instances returns a primitive value representing this date. It may either be a string or a number, depending on the hint given.

Try it

// Depending on timezone, your results will vary
const date = new Date("20 December 2019 14:48");

console.log(date[Symbol.toPrimitive]("string"));
// Expected output: "Fri Dec 20 2019 14:48:00 GMT+0530 (India Standard Time)"

console.log(date[Symbol.toPrimitive]("number"));
// Expected output: 1576833480000

Syntax

js
date[Symbol.toPrimitive](hint)

Parameters

hint

A string representing the type of the primitive value to return. The following values are valid:

  • "string" or "default": The method should return a string.
  • "number": The method should return a number.

Return value

If hint is "string" or "default", this method returns a string by coercing the this value to a string (first trying toString() then trying valueOf()).

If hint is "number", this method returns a number by coercing the this value to a number (first trying valueOf() then trying toString()).

Exceptions

TypeError

Thrown if the hint argument is not one of the three valid values.

Description

The [Symbol.toPrimitive]() method is part of the type coercion protocol. JavaScript always calls the [Symbol.toPrimitive]() method in priority to convert an object to a primitive value. You rarely need to invoke the [Symbol.toPrimitive]() method yourself; JavaScript automatically invokes it when encountering an object where a primitive value is expected.

The [Symbol.toPrimitive]() method of the Date object returns a primitive value by either invoking this.valueOf() and returning a number, or invoking this.toString() and returning a string. It exists to override the default primitive coercion process to return a string instead of a number, because primitive coercion, by default, calls valueOf() before toString(). With the custom [Symbol.toPrimitive](), new Date(0) + 1 returns "Thu Jan 01 1970 00:00:00 GMT+0000 (Coordinated Universal Time)1" (a string) instead of 1 (a number).

Examples

Using [Symbol.toPrimitive]()

js
const d = new Date(0); // 1970-01-01T00:00:00.000Z

d[Symbol.toPrimitive]("string"); // "Thu Jan 01 1970 00:00:00 GMT+0000 (Coordinated Universal Time)"
d[Symbol.toPrimitive]("number"); // 0
d[Symbol.toPrimitive]("default"); // "Thu Jan 01 1970 00:00:00 GMT+0000 (Coordinated Universal Time)"

Specifications

Specification
ECMAScript® 2025 Language Specification
# sec-date.prototype-%symbol.toprimitive%

Browser compatibility

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
[Symbol.toPrimitive]

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support

See also