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.




description Optional
Optional, string. A description of the symbol which can be used for debugging but not to access the symbol itself.


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.


Length property whose value is 0.
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

A method returning the default iterator for an object. Used by for...of.
A method that returns the default AsyncIterator for an object. Used by for await of.

Regular expression symbols

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().
A method that replaces matched substrings of a string. Used by String.prototype.replace().
A method that returns the index within a string that matches the regular expression. Used by String.prototype.search().
A method that splits a string at the indices that match a regular expression. Used by String.prototype.split().

Other symbols

A method determining if a constructor object recognizes an object as its instance. Used by instanceof.
A Boolean value indicating if an object should be flattened to its array elements. Used by Array.prototype.concat().
An object value of whose own and inherited property names are excluded from the with environment bindings of the associated object.
A constructor function that is used to create derived objects.
A method converting an object to a primitive value.
A string value used for the default description of an object. Used by Object.prototype.toString().


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.
Retrieves a shared symbol key from the global symbol registry for the given symbol.

Symbol prototype

All Symbols inherit from Symbol.prototype.


Returns the function that created an instance's prototype. This is the Symbol function by default.
A read-only string containing the description of the symbol.


Returns a string containing the source of the Symbol object. Overrides the Object.prototype.toSource() method.
Returns a string containing the description of the Symbol. Overrides the Object.prototype.toString() method.
Returns the primitive value of the Symbol object. Overrides the Object.prototype.valueOf() method.
Returns the primitive value of the Symbol object.


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 or sym | 0).
  • When using loose equality, Object(sym) == sym returns true.
  • Symbol("foo") + "bar" throws a TypeError (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 to Symbol.prototype.toString() with symbols, but note that new 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


Browser compatibilityUpdate compatibility data on GitHub

Chrome Edge Firefox Internet Explorer Opera Safari
Basic support 38 12
Edge 12 included Symbol properties in JSON.stringify() output.
36 No 25 9
asyncIterator No No No
Available in Firefox Nightly.
No No No
description 70 No 63 No 57 No
for 40 Yes 36 No Yes 9
hasInstance 51 15 50 No Yes Yes
isConcatSpreadable 48 15 48 No Yes Yes
iterator 43 Yes 36 No 30 10
keyFor 40 Yes 36 No Yes 9
match 50 Yes 40 No Yes Yes
prototype 38 12 36 No 25 9
replace 50 Yes 49 No Yes Yes
search 50 Yes 49 No Yes Yes
species 51 14 41 No 38 10
split 50 Yes 49 No Yes Yes
toPrimitive 48 15 44 No Yes Yes
toSource No No 36 No No No
toString 38 12 36 No 25 9
toStringTag 49 15 51 No Yes Yes
unscopables 38 Yes 48 No Yes 9
valueOf 38 12 36 No 25 9
@@toPrimitive ? ? 44 No ? ?
Android webview Chrome for Android Edge Mobile Firefox for Android Opera for Android iOS Safari Samsung Internet
Basic support Yes 38 Yes 36 25 9 Yes
asyncIterator No No No No No No No
description 70 70 No 63 57 No No
for Yes Yes Yes 36 Yes 9 Yes
hasInstance Yes Yes Yes 50 Yes Yes Yes
isConcatSpreadable Yes Yes Yes 48 Yes Yes Yes
iterator Yes Yes Yes 36 Yes 10 Yes
keyFor Yes Yes Yes 36 Yes 9 Yes
match Yes Yes Yes 40 Yes Yes Yes
prototype Yes 38 Yes 36 25 9 Yes
replace Yes Yes Yes 49 Yes Yes Yes
search Yes Yes Yes 49 Yes Yes Yes
species Yes Yes 14 41 38 10 Yes
split Yes Yes Yes 49 Yes Yes Yes
toPrimitive Yes Yes Yes 44 Yes Yes Yes
toSource No No No 36 No No No
toString Yes 38 Yes 36 25 9 Yes
toStringTag Yes Yes Yes 51 Yes Yes Yes
unscopables Yes Yes Yes 48 Yes 9 Yes
valueOf Yes 38 Yes 36 25 9 Yes
@@toPrimitive ? ? ? 44 ? ? ?
Basic support Yes
asyncIterator No
description No
for Yes
hasInstance 6.5.0
Disabled From version 6.0.0: this feature is behind the --harmony runtime flag.
isConcatSpreadable 6.0.0
iterator 0.12
keyFor Yes
match 6.0.0
prototype Yes
replace 6.0.0
search 6.0.0
species 6.5.0
Disabled From version 6.0.0: this feature is behind the --harmony runtime flag.
split 6.0.0
toPrimitive 6.0.0
toSource No
toString Yes
toStringTag 6.0.0
Disabled From version 4.0.0: this feature is behind the --harmony runtime flag.
unscopables 0.12
valueOf Yes
@@toPrimitive ?

See also

© 2005–2018 Mozilla Developer Network and individual contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.