symbol[Symbol.toPrimitive](hint) is the method JavaScript calls when it needs to turn a symbol object into a plain value. For a symbol the answer is always the same: it returns the symbol itself. The hint ("default", "number" or "string") is ignored.
You almost never call it yourself. It is worth knowing because it explains two things: a wrapper made with Object(symbol) behaves like the symbol in == comparisons, and a symbol still cannot be changed into a number or text by the operators, because those conversions throw a TypeError after this method has returned the symbol.
Remember
symbol[Symbol.toPrimitive](hint)
hint → "default", "number" or "string"
(ignored for symbols)
returns → the symbol itself
Number(sym), +sym, sym + 1 → TypeError
String(sym) → works
Boolean(sym) → true
Syntax
Use the well-known symbol Symbol.toPrimitive in square brackets to reach the method. The hint is optional.
Return the symbol itself. The hint changes nothing.
symbol[Symbol.toPrimitive]("string")
Return the symbol itself. The hint changes nothing.
Symbol.prototype[Symbol.toPrimitive].name
The name of the method, which is "[Symbol.toPrimitive]".
A standard JavaScript method (ES2015) on every symbol. Its name is a well-known symbol, so you write it with square brackets. No import required. Siblings: Symbol.for(), Symbol.keyFor(), toString(), valueOf().
Library declarations
JavaScript
// ECMAScript 2015 (ES6)
Symbol.prototype[Symbol.toPrimitive](hint)
// hint : "default" | "number" | "string" (ignored)
// returns: a symbol
// throws : TypeError if called on something that is not a symbol
Parameters
Parameter
Description
hint
Optional. The kind of value that JavaScript wants: "default", "number" or "string". The method accepts it because every Symbol.toPrimitive method has this shape, but for a symbol it is ignored.
Return Value
Return Value
Description
symbol
The primitive symbol. For a symbol it is the symbol itself, and for a wrapper object it is the symbol that was wrapped.
TypeError (thrown)
Only when the method is borrowed and called on a value that is not a symbol.
JavaScript Examples
Example 1 — Call It with Every Hint
Call the method with each hint and with no hint. The answer is always the symbol itself.
The method has a name. It is shared by all symbols through Symbol.prototype, and its name is "[Symbol.toPrimitive]", with the brackets.
A wrapper unwraps itself. Called on boxed, the method returns the symbol that is inside, so the comparison with id is true.
That is why == works. The loose comparison asks the wrapper for its primitive value first, so boxed == id is true. Strict === never does that, so it stays false.
Example 3 — See Which Conversions Work
Try turning a symbol into a number, into text and into a boolean. The catch block prints the error type only, because the message text differs between browsers.
Number(id) -> TypeError
+id -> TypeError
id + 1 -> TypeError
id + empty text -> TypeError
String(id) -> Symbol(id)
Boolean(id) -> true
How It Works
Numbers are not allowed.Number(id), +id and id + 1 all try to turn the symbol into a number, and JavaScript throws a TypeError.
Joining text is not allowed.id + "" would need an automatic string, so it throws too.
Two conversions work.String(id) is a special case that returns "Symbol(id)". Boolean(id) is true, because every symbol counts as truthy.
Compatibility
Browser & Runtime Support
Symbol.prototype[Symbol.toPrimitive]() is part of ES2015 (ES6). Every current browser and Node.js has it.
✓ ES2015 · Widely supported
symbol[Symbol.toPrimitive]()
Supported in Chrome 47+, Edge 15+, Firefox 44+, Safari 10+, Opera 34+ and Node.js 6+. Internet Explorer never got it.
ES2015Standard since
Google Chrome47+ · Desktop & Mobile
Full support
Microsoft Edge15+ · Chromium and legacy
Full support
Mozilla Firefox44+ · Desktop & Mobile
Full support
Apple Safari10+ · macOS & iOS
Full support
Opera34+ · Chromium based
Full support
Samsung InternetRecent versions · Android
Supported
Android WebView47+ · Chromium based
Supported
Node.js6+ · Server runtime
Supported
DenoSupported · JavaScript runtime
Supported
BunSupported · JavaScript runtime
Supported
Internet ExplorerNo native support
Not supported
symbol[Symbol.toPrimitive]()Excellent
Bottom line: Safe to use in every current browser and in Node.js. Older browsers that have Symbol but not this method still run the conversions, so you will rarely notice a difference.
Frequently Asked Questions
It is the method JavaScript uses to get a primitive value from a symbol object. For a symbol it simply returns the symbol itself and ignores the hint. You almost never call it directly.
A symbol has no number value, and JavaScript refuses to guess one. The same rule stops +symbol, symbol + 1 and symbol + "text". Convert on purpose with String(symbol), symbol.toString() or symbol.description.
They tell an object which type of value JavaScript wants: "number" for maths, "string" for text and "default" when it is not sure, such as with + or ==. A symbol ignores the hint and always returns itself.
Add a method named [Symbol.toPrimitive](hint) to a class or an object, and return a primitive value depending on the hint. For example, return a number for "number" and a text for "string". Then Number(obj) and `${obj}` use your method.
Yes. Every symbol is truthy, even Symbol() with no description. So you can write if (sym) safely, but the check does not tell you anything about the description.