JavaScript Symbol [Symbol.toPrimitive]() Method

Beginner
6 min read
Updated: Nov 2026
3 examples
Instance method

Definition

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.

JavaScript
const id = Symbol("id");

console.log(id[Symbol.toPrimitive]("default") === id);   // true
console.log(id[Symbol.toPrimitive]("number") === id);    // true
console.log(id[Symbol.toPrimitive]() === id);            // true
CallWhat it does
symbol[Symbol.toPrimitive]("default")Return the symbol itself.
symbol[Symbol.toPrimitive]("number")Return the symbol itself. The hint changes nothing.
symbol[Symbol.toPrimitive]("string")Return the symbol itself. The hint changes nothing.
Symbol.prototype[Symbol.toPrimitive].nameThe 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

ParameterDescription
hintOptional. 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 ValueDescription
symbolThe 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.

JavaScript
const id = Symbol("id");

console.log("default: " + (id[Symbol.toPrimitive]("default") === id));
console.log("number: " + (id[Symbol.toPrimitive]("number") === id));
console.log("string: " + (id[Symbol.toPrimitive]("string") === id));
console.log("no hint: " + (id[Symbol.toPrimitive]() === id));
Try It Yourself

How It Works

  1. Reach the method. id[Symbol.toPrimitive] uses the well-known symbol as the property name, so the square brackets are required.
  2. Try every hint. The hint tells an object which kind of value is wanted. A symbol has only one possible value, so it ignores the hint.
  3. Always the symbol. Every comparison with id is true, even when no hint is passed at all.

Example 2 — Unwrap a Symbol Object

Look at the name of the method, and see how a wrapper made with Object(symbol) uses it.

JavaScript
const id = Symbol("id");
const boxed = Object(id);

console.log("Method name: " + Symbol.prototype[Symbol.toPrimitive].name);
console.log("boxed to primitive: " + (boxed[Symbol.toPrimitive]("default") === id));
console.log("boxed == id: " + (boxed == id));
console.log("boxed === id: " + (boxed === id));
Try It Yourself

How It Works

  1. The method has a name. It is shared by all symbols through Symbol.prototype, and its name is "[Symbol.toPrimitive]", with the brackets.
  2. A wrapper unwraps itself. Called on boxed, the method returns the symbol that is inside, so the comparison with id is true.
  3. 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.

JavaScript
const id = Symbol("id");

const tests = [
  ["Number(id)", () => Number(id)],
  ["+id", () => +id],
  ["id + 1", () => id + 1],
  ["id + empty text", () => id + ""],
  ["String(id)", () => String(id)],
  ["Boolean(id)", () => Boolean(id)]
];

for (const [label, test] of tests) {
  try {
    console.log(label + " -> " + test());
  } catch (err) {
    console.log(label + " -> " + err.name);
  }
}
Try It Yourself

How It Works

  1. Numbers are not allowed. Number(id), +id and id + 1 all try to turn the symbol into a number, and JavaScript throws a TypeError.
  2. Joining text is not allowed. id + "" would need an automatic string, so it throws too.
  3. Two conversions work. String(id) is a special case that returns "Symbol(id)". Boolean(id) is true, because every symbol counts as truthy.

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.

ES2015 Standard since
Google Chrome 47+ · Desktop & Mobile
Full support
Microsoft Edge 15+ · Chromium and legacy
Full support
Mozilla Firefox 44+ · Desktop & Mobile
Full support
Apple Safari 10+ · macOS & iOS
Full support
Opera 34+ · Chromium based
Full support
Samsung Internet Recent versions · Android
Supported
Android WebView 47+ · Chromium based
Supported
Node.js 6+ · Server runtime
Supported
Deno Supported · JavaScript runtime
Supported
Bun Supported · JavaScript runtime
Supported
Internet Explorer No 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.

Back to the method index

See all five Symbol method guides grouped by what they do, with a short description for each.

Symbol Methods index →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

9 people found this page helpful