The Symbol()
function returns a value of type symbol, has static properties that expose several members of built-in objects, has static methods that expose the global symbol registry, and resembles a built-in object class but is incomplete as a constructor because it does not support the syntax "new Symbol()
".
Every symbol value returned from Symbol()
is unique. A symbol value may be used as an identifier for object properties; this is the data type's only purpose. Some further explanation about purpose and usage can be found in the glossary entry for Symbol.
The data type symbol is a primitive data type.
The source for this interactive example is stored in a GitHub repository. If you'd like to contribute to the interactive examples project, please clone https://github.com/mdn/interactive-examples and send us a pull request.
Syntax
Symbol([description])
Parameters
description
Optional- Optional, string. A description of the symbol which can be used for debugging but not to access the symbol itself.
Description
To create a new primitive symbol, you write Symbol()
with an optional string as its description:
var sym1 = Symbol(); var sym2 = Symbol('foo'); var sym3 = Symbol('foo');
The above code creates three new symbols. Note that Symbol("foo")
does not coerce the string "foo" into a symbol. It creates a new symbol each time:
Symbol('foo') === Symbol('foo'); // false
The following syntax with the new
operator will throw a TypeError
:
var sym = new Symbol(); // TypeError
This prevents authors from creating an explicit Symbol
wrapper object instead of a new symbol value and might be surprising as creating explicit wrapper objects around primitive data types is generally possible (for example, new Boolean
, new String
and new Number
).
If you really want to create a Symbol
wrapper object, you can use the Object()
function:
var sym = Symbol('foo'); typeof sym; // "symbol" var symObj = Object(sym); typeof symObj; // "object"
Shared symbols in the global symbol registry
The above syntax using the Symbol()
function will not create a global symbol that is available in your whole codebase. To create symbols available across files and even across realms (each of which has its own global scope), use the methods Symbol.for()
and Symbol.keyFor()
to set and retrieve symbols from the global symbol registry.
Finding symbol properties on objects
The method Object.getOwnPropertySymbols()
returns an array of symbols and lets you find symbol properties on a given object. Note that every object is initialized with no own symbol properties, so that this array will be empty unless you've set symbol properties on the object.
Properties
Symbol.length
- Length property whose value is 0.
Symbol.prototype
- Represents the prototype for the
Symbol
constructor.
Well-known symbols
In addition to your own symbols, JavaScript has some built-in symbols which represent internal language behaviors which were not exposed to developers in ECMAScript 5 and before. These symbols can be accessed using the following properties:
Iteration symbols
Symbol.iterator
- A method returning the default iterator for an object. Used by
for...of
. Symbol.asyncIterator
- A method that returns the default AsyncIterator for an object. Used by
for await of
.
Regular expression symbols
Symbol.match
- A method that matches against a string, also used to determine if an object may be used as a regular expression. Used by
String.prototype.match()
. Symbol.matchAll
- A method that returns an iterator, that yields matches of the regular expression against a string. Used by
String.prototype.matchAll()
. Symbol.replace
- A method that replaces matched substrings of a string. Used by
String.prototype.replace()
. Symbol.search
- A method that returns the index within a string that matches the regular expression. Used by
String.prototype.search()
. Symbol.split
- A method that splits a string at the indices that match a regular expression. Used by
String.prototype.split()
.
Other symbols
Symbol.hasInstance
- A method determining if a constructor object recognizes an object as its instance. Used by
instanceof
. Symbol.isConcatSpreadable
- A Boolean value indicating if an object should be flattened to its array elements. Used by
Array.prototype.concat()
. Symbol.unscopables
- An object value of whose own and inherited property names are excluded from the
with
environment bindings of the associated object. Symbol.species
- A constructor function that is used to create derived objects.
Symbol.toPrimitive
- A method converting an object to a primitive value.
Symbol.toStringTag
- A string value used for the default description of an object. Used by
Object.prototype.toString()
.
Methods
Symbol.for(key)
- Searches for existing symbols with the given key and returns it if found. Otherwise a new symbol gets created in the global symbol registry with this key.
Symbol.keyFor(sym)
- Retrieves a shared symbol key from the global symbol registry for the given symbol.
Symbol prototype
All Symbols inherit from Symbol.prototype
.
Properties
Symbol.prototype.constructor
- Returns the function that created an instance's prototype. This is the
Symbol
function by default. Symbol.prototype.description
- A read-only string containing the description of the symbol.
Methods
Symbol.prototype.toSource()
- Returns a string containing the source of the
Symbol
object. Overrides theObject.prototype.toSource()
method. Symbol.prototype.toString()
- Returns a string containing the description of the Symbol. Overrides the
Object.prototype.toString()
method. Symbol.prototype.valueOf()
- Returns the primitive value of the
Symbol
object. Overrides theObject.prototype.valueOf()
method. Symbol.prototype[@@toPrimitive]
- Returns the primitive value of the
Symbol
object.
Examples
Using the typeof operator with symbols
The typeof
operator can help you to identify symbols.
typeof Symbol() === 'symbol' typeof Symbol('foo') === 'symbol' typeof Symbol.iterator === 'symbol'
Symbol type conversions
Some things to note when working with type conversion of symbols.
- When trying to convert a symbol to a number, a
TypeError
will be thrown
(e.g.+sym
orsym | 0
). - When using loose equality,
Object(sym) == sym
returnstrue.
Symbol("foo") + "bar"
throws aTypeError
(can't convert symbol to string). This prevents you from silently creating a new string property name from a symbol, for example.- The "safer"
String(sym)
conversion works like a call toSymbol.prototype.toString()
with symbols, but note thatnew String(sym)
will throw.
Symbols and for...in iteration
Symbols are not enumerable in for...in
iterations. In addition, Object.getOwnPropertyNames()
will not return symbol object properties, however, you can use Object.getOwnPropertySymbols()
to get these.
var obj = {}; obj[Symbol('a')] = 'a'; obj[Symbol.for('b')] = 'b'; obj['c'] = 'c'; obj.d = 'd'; for (var i in obj) { console.log(i); // logs "c" and "d" }
Symbols and JSON.stringify()
Symbol-keyed properties will be completely ignored when using JSON.stringify()
:
JSON.stringify({[Symbol('foo')]: 'foo'}); // '{}'
For more details, see JSON.stringify()
.
Symbol wrapper objects as property keys
When a Symbol wrapper object is used as a property key, this object will be coerced to its wrapped symbol:
var sym = Symbol('foo'); var obj = {[sym]: 1}; obj[sym]; // 1 obj[Object(sym)]; // still 1
Specifications
Specification | Status | Comment |
---|---|---|
ECMAScript 2015 (6th Edition, ECMA-262) The definition of 'Symbol' in that specification. |
Standard | Initial definition |
ECMAScript Latest Draft (ECMA-262) The definition of 'Symbol' in that specification. |
Draft |
Browser compatibility
Desktop | Mobile | Server | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Basic support | Chrome Full support 38 | Edge
Full support
12
| Firefox Full support 36 | IE No support No | Opera Full support 25 | Safari Full support 9 | WebView Android Full support 38 | Chrome Android Full support 38 | Edge Mobile Full support Yes | Firefox Android Full support 36 | Opera Android Full support 25 | Safari iOS Full support 9 | Samsung Internet Android Full support Yes | nodejs Full support Yes |
asyncIterator | Chrome Full support 63 | Edge No support No | Firefox
No support
No
| IE No support No | Opera No support No | Safari No support No | WebView Android Full support 63 | Chrome Android Full support 63 | Edge Mobile No support No | Firefox Android No support No | Opera Android No support No | Safari iOS No support No | Samsung Internet Android No support No | nodejs No support No |
description | Chrome Full support 70 | Edge No support No | Firefox Full support 63 | IE No support No | Opera Full support 57 | Safari No support No | WebView Android Full support 70 | Chrome Android Full support 70 | Edge Mobile No support No | Firefox Android Full support 63 | Opera Android Full support 57 | Safari iOS No support No | Samsung Internet Android No support No | nodejs No support No |
for | Chrome Full support 40 | Edge Full support Yes | Firefox Full support 36 | IE No support No | Opera Full support Yes | Safari Full support 9 | WebView Android Full support 40 | Chrome Android Full support 40 | Edge Mobile Full support Yes | Firefox Android Full support 36 | Opera Android Full support Yes | Safari iOS Full support 9 | Samsung Internet Android Full support Yes | nodejs Full support Yes |
hasInstance | Chrome Full support 50 | Edge Full support 15 | Firefox Full support 50 | IE No support No | Opera Full support Yes | Safari Full support Yes | WebView Android Full support 50 | Chrome Android Full support 50 | Edge Mobile Full support Yes | Firefox Android Full support 50 | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes | nodejs
Full support
6.5.0
|
isConcatSpreadable | Chrome Full support 48 | Edge Full support 15 | Firefox Full support 48 | IE No support No | Opera Full support Yes | Safari Full support Yes | WebView Android Full support 48 | Chrome Android Full support 48 | Edge Mobile Full support Yes | Firefox Android Full support 48 | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes | nodejs Full support 6.0.0 |
iterator | Chrome Full support 43 | Edge Full support Yes | Firefox Full support 36 | IE No support No | Opera Full support 30 | Safari Full support 10 | WebView Android Full support 43 | Chrome Android Full support 43 | Edge Mobile Full support Yes | Firefox Android Full support 36 | Opera Android Full support Yes | Safari iOS Full support 10 | Samsung Internet Android Full support Yes | nodejs Full support 0.12 |
keyFor | Chrome Full support 40 | Edge Full support Yes | Firefox Full support 36 | IE No support No | Opera Full support Yes | Safari Full support 9 | WebView Android Full support 40 | Chrome Android Full support 40 | Edge Mobile Full support Yes | Firefox Android Full support 36 | Opera Android Full support Yes | Safari iOS Full support 9 | Samsung Internet Android Full support Yes | nodejs Full support Yes |
match | Chrome Full support 50 | Edge Full support Yes | Firefox Full support 40 | IE No support No | Opera Full support Yes | Safari Full support Yes | WebView Android Full support 50 | Chrome Android Full support 50 | Edge Mobile Full support Yes | Firefox Android Full support 40 | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes | nodejs Full support 6.0.0 |
matchAll | Chrome Full support 73 | Edge No support No | Firefox No support No | IE No support No | Opera Full support 60 | Safari No support No | WebView Android Full support 73 | Chrome Android Full support 73 | Edge Mobile No support No | Firefox Android No support No | Opera Android Full support Yes | Safari iOS No support No | Samsung Internet Android Full support Yes | nodejs No support No |
prototype | Chrome Full support 38 | Edge Full support 12 | Firefox Full support 36 | IE No support No | Opera Full support 25 | Safari Full support 9 | WebView Android Full support 38 | Chrome Android Full support 38 | Edge Mobile Full support Yes | Firefox Android Full support 36 | Opera Android Full support 25 | Safari iOS Full support 9 | Samsung Internet Android Full support Yes | nodejs Full support Yes |
replace | Chrome Full support 50 | Edge Full support Yes | Firefox Full support 49 | IE No support No | Opera Full support Yes | Safari Full support Yes | WebView Android Full support 50 | Chrome Android Full support 50 | Edge Mobile Full support Yes | Firefox Android Full support 49 | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes | nodejs Full support 6.0.0 |
search | Chrome Full support 50 | Edge Full support Yes | Firefox Full support 49 | IE No support No | Opera Full support Yes | Safari Full support Yes | WebView Android Full support 50 | Chrome Android Full support 50 | Edge Mobile Full support Yes | Firefox Android Full support 49 | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes | nodejs Full support 6.0.0 |
species | Chrome Full support 51 | Edge Full support 14 | Firefox Full support 41 | IE No support No | Opera Full support 38 | Safari Full support 10 | WebView Android Full support 51 | Chrome Android Full support 51 | Edge Mobile Full support 14 | Firefox Android Full support 41 | Opera Android Full support 38 | Safari iOS Full support 10 | Samsung Internet Android Full support Yes | nodejs
Full support
6.5.0
|
split | Chrome Full support 50 | Edge Full support Yes | Firefox Full support 49 | IE No support No | Opera Full support Yes | Safari Full support Yes | WebView Android Full support 50 | Chrome Android Full support 50 | Edge Mobile Full support Yes | Firefox Android Full support 49 | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes | nodejs Full support 6.0.0 |
toPrimitive | Chrome Full support 47 | Edge Full support 15 | Firefox Full support 44 | IE No support No | Opera Full support Yes | Safari Full support Yes | WebView Android Full support 47 | Chrome Android Full support 47 | Edge Mobile Full support Yes | Firefox Android Full support 44 | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes | nodejs Full support 6.0.0 |
toSource | Chrome No support No | Edge No support No | Firefox Full support 36 | IE No support No | Opera No support No | Safari No support No | WebView Android No support No | Chrome Android No support No | Edge Mobile No support No | Firefox Android Full support 36 | Opera Android No support No | Safari iOS No support No | Samsung Internet Android No support No | nodejs No support No |
toString | Chrome Full support 38 | Edge Full support 12 | Firefox Full support 36 | IE No support No | Opera Full support 25 | Safari Full support 9 | WebView Android Full support 38 | Chrome Android Full support 38 | Edge Mobile Full support Yes | Firefox Android Full support 36 | Opera Android Full support 25 | Safari iOS Full support 9 | Samsung Internet Android Full support Yes | nodejs Full support Yes |
toStringTag | Chrome Full support 49 | Edge Full support 15 | Firefox Full support 51 | IE No support No | Opera Full support Yes | Safari Full support Yes | WebView Android Full support 49 | Chrome Android Full support 49 | Edge Mobile Full support Yes | Firefox Android Full support 51 | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes | nodejs
Full support
6.0.0
|
unscopables | Chrome Full support 45 | Edge Full support Yes | Firefox Full support 48 | IE No support No | Opera Full support Yes | Safari Full support 9 | WebView Android Full support 45 | Chrome Android Full support 45 | Edge Mobile Full support Yes | Firefox Android Full support 48 | Opera Android Full support Yes | Safari iOS Full support 9 | Samsung Internet Android Full support Yes | nodejs Full support 0.12 |
valueOf | Chrome Full support 38 | Edge Full support 12 | Firefox Full support 36 | IE No support No | Opera Full support 25 | Safari Full support 9 | WebView Android Full support 38 | Chrome Android Full support 38 | Edge Mobile Full support Yes | Firefox Android Full support 36 | Opera Android Full support 25 | Safari iOS Full support 9 | Samsung Internet Android Full support Yes | nodejs Full support Yes |
@@toPrimitive | Chrome ? | Edge ? | Firefox Full support 44 | IE No support No | Opera ? | Safari ? | WebView Android ? | Chrome Android ? | Edge Mobile ? | Firefox Android Full support 44 | Opera Android ? | Safari iOS ? | Samsung Internet Android ? | nodejs ? |
Legend
- Full support
- Full support
- No support
- No support
- Compatibility unknown
- Compatibility unknown
- Experimental. Expect behavior to change in the future.
- Experimental. Expect behavior to change in the future.
- Non-standard. Expect poor cross-browser support.
- Non-standard. Expect poor cross-browser support.
- See implementation notes.
- See implementation notes.
- User must explicitly enable this feature.
- User must explicitly enable this feature.