TheSymbol.toPrimitive static data property represents thewell-known symbolSymbol.toPrimitive. Alltype coercion algorithms look up this symbol on objects for the method that accepts a preferred type and returns a primitive representation of the object, before falling back to using the object'svalueOf() andtoString() methods.

Try it

const object = {  [Symbol.toPrimitive](hint) {    if (hint === "number") {      return 42;    }    return null;  },};console.log(+object);// Expected output: 42

Value

The well-known symbolSymbol.toPrimitive.

Description

With the help of theSymbol.toPrimitive property (used as a function value), an object can be converted to a primitive value. The function is called with a string argumenthint, which specifies the preferred type of the result primitive value. Thehint argument can be one of"number","string", and"default".

The"number" hint is used bynumeric coercion algorithms. The"string" hint is used by thestring coercion algorithm. The"default" hint is used by theprimitive coercion algorithm. Thehint only acts as a weak signal of preference, and the implementation is free to ignore it (asSymbol.prototype[Symbol.toPrimitive]() does). The language does not enforce alignment between thehint and the result type, although[Symbol.toPrimitive]() must return a primitive, or aTypeError is thrown.

Objects without the[Symbol.toPrimitive] property are converted to primitives by calling thevalueOf() andtoString() methods in different orders, which is explained in more detail in thetype coercion section.[Symbol.toPrimitive]() allows full control over the primitive conversion process. For example,Date.prototype[Symbol.toPrimitive]() treats"default" as if it's"string" and callstoString() instead ofvalueOf().Symbol.prototype[Symbol.toPrimitive]() ignores the hint and always returns a symbol, which means even in string contexts,Symbol.prototype.toString() won't be called, andSymbol objects must always be explicitly converted to strings throughString().

Examples

Modifying primitive values converted from an object

Following example describes howSymbol.toPrimitive property can modify the primitive value converted from an object.

// An object without Symbol.toPrimitive property.const obj1 = {};console.log(+obj1); // NaNconsole.log(`${obj1}`); // "[object Object]"console.log(obj1 + ""); // "[object Object]"// An object with Symbol.toPrimitive property.const obj2 = {  [Symbol.toPrimitive](hint) {    if (hint === "number") {      return 10;    }    if (hint === "string") {      return "hello";    }    return true;  },};console.log(+obj2); // 10        — hint is "number"console.log(`${obj2}`); // "hello"   — hint is "string"console.log(obj2 + ""); // "true"    — hint is "default"

Specifications

Browser compatibility

See also

• Polyfill ofSymbol.toPrimitive incore-js
• Date.prototype[Symbol.toPrimitive]()
• Symbol.prototype[Symbol.toPrimitive]()
• Object.prototype.toString()
• Object.prototype.valueOf()