symbol.valueOf() returns the primitive symbol that a value stands for. Called on a normal symbol, it simply returns that same symbol. Called on a symbol wrapper object (made with Object(symbol)), it returns the symbol that is inside the wrapper.
You will almost never need it in everyday code, because JavaScript calls it for you when it needs the plain value. It helps you understand why a wrapper object and a symbol are two different things: Object(sym) === sym is false, but Object(sym).valueOf() === sym is true.
Remember
symbol.valueOf()
symbol → the same symbol
Object(symbol) → the symbol inside
typeof symbol → "symbol"
typeof Object(symbol) → "object"
Object(sym).valueOf() === sym
Syntax
Call it on a symbol or on a symbol wrapper object. It takes no arguments.
boxed == id: true
boxed === id: false
As a key: found
Strict, after valueOf(): true
Not a symbol: TypeError
How It Works
Loose and strict equality.== unwraps the object before comparing, so it is true. === never unwraps, so it is false.
As a property key. When an object is used inside [ ], JavaScript first converts it to its primitive value. The wrapper becomes the symbol, so data[boxed] finds "found".
Wrong receiver.valueOf() only accepts a symbol or a symbol wrapper. Borrowing it for the string "text" throws a TypeError.
Compatibility
Browser & Runtime Support
Symbol.prototype.valueOf() is part of ES2015 (ES6). Every current browser and Node.js has it.
✓ ES2015 · Widely supported
symbol.valueOf()
Supported in Chrome 38+, Edge 12+, Firefox 36+, Safari 9+, Opera 25+ and Node.js 0.12+. Internet Explorer never got it.
ES2015Standard since
Google Chrome38+ · Desktop & Mobile
Full support
Microsoft Edge12+ · Chromium and legacy
Full support
Mozilla Firefox36+ · Desktop & Mobile
Full support
Apple Safari9+ · macOS & iOS
Full support
Opera25+ · Chromium based
Full support
Samsung InternetRecent versions · Android
Supported
Android WebView38+ · Chromium based
Supported
Node.js0.12+ · Server runtime
Supported
DenoSupported · JavaScript runtime
Supported
BunSupported · JavaScript runtime
Supported
Internet ExplorerNo native support
Not supported
symbol.valueOf()Excellent
Bottom line: Safe to use in every current browser and in Node.js. The only thing to plan for is Internet Explorer, which has no Symbol at all.
Frequently Asked Questions
It returns the primitive symbol of a value. On a normal symbol it returns the same symbol. On a symbol wrapper object, made with Object(symbol), it returns the symbol that is inside the wrapper.
Object(symbol) creates an object, and a symbol is a primitive. An object and a primitive are never strictly equal. Use Object(symbol).valueOf() === symbol, or the loose comparison ==, which unwraps the object first.
Call Object(symbol). The usual new Symbol("id") does not work and throws a TypeError, because Symbol is not a constructor. Wrapper objects are rarely useful, so most code never needs one.
Almost never. JavaScript calls it for you when it needs the plain value, for example in a comparison with == or when a wrapper is used as a property key. Call it yourself only if you receive a wrapper object and want the symbol.
valueOf() returns the symbol itself. toString() returns text such as "Symbol(id)". Use valueOf() when you need the symbol, and toString() when you need something to print.