W3cubDocs

/JavaScript

Symbol

The data type symbol is a primitive data type. 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 primary purpose, although other use-cases exist, such as enabling opaque data types, or serving as an implementation-supported unique identifier in general. Some further explanation about purpose and usage can be found in the glossary entry for Symbol.

Description

To create a new primitive symbol, you write Symbol() with an optional string as its description:

let sym1 = Symbol()
let sym2 = Symbol('foo')
let 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:

let 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:

let sym = Symbol('foo')
typeof sym      // "symbol" 
let 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.

Constructor

Symbol()
Creates a new Symbol object. It is incomplete as a constructor because it does not support the syntax "new Symbol()".

Static properties

Symbol.asyncIterator
A method that returns the default AsyncIterator for an object. Used by for await...of.
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.iterator
A method returning the default iterator for an object. Used by for...of.
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().
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().
Symbol.unscopables
An object value of whose own and inherited property names are excluded from the with environment bindings of the associated object.

Static 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 key.
Symbol.keyFor(sym)
Retrieves a shared symbol key from the global symbol registry for the given symbol.

Instance properties

Symbol.prototype.description
A read-only string containing the description of the symbol.

Instance methods

Symbol.prototype.toSource()
Returns a string containing the source of the Symbol object. Overrides the Object.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 the Object.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 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.

let obj = {}

obj[Symbol('a')] = 'a'
obj[Symbol.for('b')] = 'b'
obj['c'] = 'c'
obj.d = 'd'

for (let 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:

let sym = Symbol('foo')
let obj = {[sym]: 1}
obj[sym]             // 1
obj[Object(sym)]     // still 1

Specifications

Browser compatibilityUpdate compatibility data on GitHub

Desktop
Chrome Edge Firefox Internet Explorer Opera Safari
Symbol 38 12
12
Edge 12 included Symbol properties in JSON.stringify() output.
36 No 25 9
Symbol() constructor 38 12 36 No 25 9
asyncIterator 63 79 57 No 50 11.1
description 70 79 63 No 57 12.1
12.1
12
No support for an undefined description.
for 40 12 36 No 27 9
hasInstance 50 15 50 No 37 10
isConcatSpreadable 48 15 48 No 35 10
iterator 43 12 36 No 30 10
keyFor 40 12 36 No 27 9
match 50 79 40 No 37 10
matchAll 73 79 67 No 60 13
replace 50 79 49 No 37 10
search 50 79 49 No 37 10
species 51 13 41 No 38 10
split 50 79 49 No 37 10
toPrimitive 47 15 44 No 34 10
toSource No No 36 — 74
36 — 74
Starting in Firefox 74, toSource() is no longer available for use by web content. It is still allowed for internal and privileged code.
No No No
toString 38 12 36 No 25 9
toStringTag 49 15 51 No 36 10
unscopables 45 12 48 No 32 9
valueOf 38 12 36 No 25 9
@@toPrimitive 47 15 44 No 34 10
Mobile
Android webview Chrome for Android Firefox for Android Opera for Android Safari on iOS Samsung Internet
Symbol 38 38 36 25 9 3.0
Symbol() constructor 38 38 36 25 9 3.0
asyncIterator 63 63 No 46 No 8.0
description 70 70 63 49 12.2
12.2
12
No support for an undefined description.
10.0
for 40 40 36 27 9 4.0
hasInstance 50 50 50 37 10 5.0
isConcatSpreadable 48 48 48 35 10 5.0
iterator 43 43 36 30 10 4.0
keyFor 40 40 36 27 9 4.0
match 50 50 40 37 10 5.0
matchAll 73 73 67 52 13 No
replace 50 50 49 37 10 5.0
search 50 50 49 37 10 5.0
species 51 51 41 41 10 5.0
split 50 50 49 37 10 5.0
toPrimitive 47 47 44 34 10 5.0
toSource No No 36 No No No
toString 38 38 36 25 9 3.0
toStringTag 49 49 51 36 10 5.0
unscopables 45 45 48 32 9 5.0
valueOf 38 38 36 25 9 3.0
@@toPrimitive 47 47 44 34 10 5.0
Server
Node.js
Symbol 0.12
Symbol() constructor 0.12
asyncIterator 10.0.0
description 11.0.0
for 0.12
hasInstance 6.5.0
6.5.0
6.0.0
Disabled
Disabled From version 6.0.0: this feature is behind the --harmony runtime flag.
isConcatSpreadable 6.0.0
iterator 0.12
keyFor 0.12
match 6.0.0
matchAll 12.0.0
replace 6.0.0
search 6.0.0
species 6.5.0
6.5.0
6.0.0
Disabled
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 0.12
toStringTag 6.0.0
6.0.0
4.0.0
Disabled
Disabled From version 4.0.0: this feature is behind the --harmony runtime flag.
unscopables 0.12
valueOf 0.12
@@toPrimitive 6.0.0

See also

© 2005–2018 Mozilla Developer Network and individual contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol