A symbol is a unique and immutable data type and may be used as an identifier for object properties. The Symbol object is an implicit object wrapper for the symbol {{Glossary("Primitive", "primitive data type")}}.
Syntax
Symbol([description])
Parameters
description
{{optional_inline}}- 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 {{jsxref("Operators/new", "new")}} operator will throw a {{jsxref("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 {{jsxref("Symbol.for()")}} and {{jsxref("Symbol.keyFor()")}} to set and retrieve symbols from the global symbol registry.
Finding symbol properties on objects
The method {{jsxref("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.
- {{jsxref("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
- {{jsxref("Symbol.iterator")}}
- A method returning the default iterator for an object. Used by
for...of
.
Regular expression symbols
- {{jsxref("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 {{jsxref("String.prototype.match()")}}.
- {{jsxref("Symbol.replace")}}
- A method that replaces matched substrings of a string. Used by {{jsxref("String.prototype.replace()")}}.
- {{jsxref("Symbol.search")}}
- A method that returns the index within a string that matches the regular expression. Used by {{jsxref("String.prototype.search()")}}.
- {{jsxref("Symbol.split")}}
- A method that splits a string at the indices that match a regular expression. Used by {{jsxref("String.prototype.split()")}}.
Other symbols
- {{jsxref("Symbol.hasInstance")}}
- A method determining if a constructor object recognizes an object as its instance. Used by {{jsxref("Operators/instanceof", "instanceof")}}.
- {{jsxref("Symbol.isConcatSpreadable")}}
- A Boolean value indicating if an object should be flattened to its array elements. Used by {{jsxref("Array.prototype.concat()")}}.
- {{jsxref("Symbol.unscopables")}}
- An object value of whose own and inherited property names are excluded from the
with
environment bindings of the associated object. - {{jsxref("Symbol.species")}}
- A constructor function that is used to create derived objects.
- {{jsxref("Symbol.toPrimitive")}}
- A method converting an object to a primitive value.
- {{jsxref("Symbol.toStringTag")}}
- A string value used for the default description of an object. Used by {{jsxref("Object.prototype.toString()")}}.
Methods
- {{jsxref("Symbol.for()", "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.
- {{jsxref("Symbol.keyFor", "Symbol.keyFor(sym)")}}
- Retrieves a shared symbol key from the global symbol registry for the given symbol.
Symbol
prototype
All Symbols inherit from {{jsxref("Symbol.prototype")}}.
Properties
{{page('en-US/Web/JavaScript/Reference/Global_Objects/Symbol/prototype','Properties')}}
Methods
{{page('en-US/Web/JavaScript/Reference/Global_Objects/Symbol/prototype','Methods')}}
Examples
Using the typeof
operator with symbols
The {{jsxref("Operators/typeof", "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 {{jsxref("TypeError")}} will be thrown
(e.g.+sym
orsym | 0
). - When using loose equality,
Object(sym) == sym
returnstrue.
Symbol("foo") + "bar"
throws a {{jsxref("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 {{jsxref("Symbol.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, {{jsxref("Object.getOwnPropertyNames()")}} will not return symbol object properties, however, you can use {{jsxref("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 {{jsxref("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 |
---|---|---|
{{SpecName('ES6', '#sec-symbol-objects', 'Symbol')}} | {{Spec2('ES6')}} | Initial definition |
{{SpecName('ESDraft', '#sec-symbol-objects', 'Symbol')}} | {{Spec2('ESDraft')}} |
Browser compatibility
{{CompatibilityTable}}
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|
Basic support | {{CompatChrome(38)}} | {{CompatGeckoDesktop(36)}} | {{CompatNo}} | 25 | 9 |
Symbol.iterator (@@iterator) | {{CompatChrome(38)}} | {{CompatGeckoDesktop(36)}} | {{CompatNo}} | 25 | 9 |
Symbol.unscopables (@@unscopables) | {{CompatChrome(38)}} | {{CompatGeckoDesktop(48)}} | {{CompatNo}} | 25 | 9 |
Symbol.match (@@match) | {{CompatUnknown}} | {{CompatGeckoDesktop(40)}} | {{CompatNo}} | {{CompatUnknown}} | {{CompatUnknown}} |
Symbol.species (@@species) | {{CompatUnknown}} | {{CompatGeckoDesktop(41)}} | {{CompatNo}} | {{CompatUnknown}} | {{CompatUnknown}} |
Symbol.toPrimitive (@@toPrimitive) | {{CompatUnknown}} | {{CompatGeckoDesktop(44)}} | {{CompatNo}} | {{CompatUnknown}} | {{CompatUnknown}} |
Symbol.replace (@@replace) | {{CompatUnknown}} | {{CompatGeckoDesktop(48)}} | {{CompatNo}} | {{CompatUnknown}} | {{CompatUnknown}} |
Symbol.search (@@search) | {{CompatUnknown}} | {{CompatGeckoDesktop(48)}} | {{CompatNo}} | {{CompatUnknown}} | {{CompatUnknown}} |
Symbol.split (@@split) | {{CompatUnknown}} | {{CompatGeckoDesktop(48)}} | {{CompatNo}} | {{CompatUnknown}} | {{CompatUnknown}} |
Symbol.isConcatSpreadable (@@isconcatspreadable) | {{CompatUnknown}} | {{CompatGeckoDesktop(48)}} | {{CompatNo}} | {{CompatUnknown}} | {{CompatUnknown}} |
Symbol.hasInstance (@@hasInstance) | {{CompatUnknown}} | {{CompatGeckoDesktop(50)}} | {{CompatNo}} | {{CompatUnknown}} | {{CompatUnknown}} |
Symbol.toStringTag (@@toStringTag) | {{CompatUnknown}} | {{CompatNo}} | {{CompatNo}} | {{CompatUnknown}} | {{CompatUnknown}} |
Feature | Android | Chrome for Android | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|
Basic support | {{CompatUnknown}} | {{CompatChrome(38)}} | {{CompatGeckoMobile(36)}} | {{CompatNo}} | 25 | 9 |
Symbol.iterator (@@iterator) | {{CompatUnknown}} | {{CompatChrome(38)}} | {{CompatGeckoMobile(36)}} | {{CompatNo}} | 25 | 9 |
Symbol.unscopables (@@unscopables) | {{CompatUnknown}} | {{CompatChrome(38)}} | {{CompatGeckoMobile(48)}} | {{CompatNo}} | 25 | 9 |
Symbol.match (@@match) | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatGeckoMobile(40)}} | {{CompatNo}} | {{CompatUnknown}} | {{CompatUnknown}} |
Symbol.species (@@species) | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatGeckoMobile(41)}} | {{CompatNo}} | {{CompatUnknown}} | {{CompatUnknown}} |
Symbol.toPrimitive (@@toPrimitive) | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatGeckoMobile(44)}} | {{CompatNo}} | {{CompatUnknown}} | {{CompatUnknown}} |
Symbol.replace (@@replace) | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatGeckoMobile(48)}} | {{CompatNo}} | {{CompatUnknown}} | {{CompatUnknown}} |
Symbol.search (@@search) | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatGeckoMobile(48)}} | {{CompatNo}} | {{CompatUnknown}} | {{CompatUnknown}} |
Symbol.split (@@split) | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatGeckoMobile(48)}} | {{CompatNo}} | {{CompatUnknown}} | {{CompatUnknown}} |
Symbol.isConcatSpreadable (@@isconcatspreadable) | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatGeckoMobile(48)}} | {{CompatNo}} | {{CompatUnknown}} | {{CompatUnknown}} |
Symbol.hasInstance (@@hasInstance) | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatGeckoMobile(50)}} | {{CompatNo}} | {{CompatUnknown}} | {{CompatUnknown}} |
Symbol.toStringTag (@@toStringTag) | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatNo}} | {{CompatNo}} | {{CompatUnknown}} | {{CompatUnknown}} |
See also
- Glossary: Symbol data type
- {{jsxref("Operators/typeof", "typeof")}}
- Data types and data structures
- "ES6 In Depth: Symbols" on hacks.mozilla.org