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
Symbolconstructor.
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
withenvironment 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.+symorsym | 0). - When using loose equality,
Object(sym) == symreturnstrue. 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 visible 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.0")}} | {{CompatNo}} | 25 | 9 |
| Symbol.iterator (@@iterator) | {{CompatChrome(38)}} | {{CompatGeckoDesktop("36.0")}} | {{CompatNo}} | 25 | 9 |
| Symbol.unscopables (@@unscopables) | {{CompatChrome(38)}} | {{CompatGeckoDesktop("48.0")}} | {{CompatNo}} | 25 | 9 |
| Symbol.match (@@match) | {{CompatNo}} | {{CompatGeckoDesktop("40.0")}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
| Symbol.species (@@species) | {{CompatNo}} | {{CompatGeckoDesktop("41.0")}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
| Symbol.toPrimitive (@@toPrimitive) | {{CompatNo}} | {{CompatGeckoDesktop("44.0")}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
| Symbol.replace (@@replace) | {{CompatNo}} | {{CompatGeckoDesktop("48.0")}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
| Symbol.search (@@search) | {{CompatNo}} | {{CompatGeckoDesktop("48.0")}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
| Symbol.split (@@split) | {{CompatNo}} | {{CompatGeckoDesktop("48.0")}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
| Other well-known symbols | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
| Feature | Android | Chrome for Android | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile |
|---|---|---|---|---|---|---|
| Basic support | {{CompatNo}} | {{CompatChrome(38)}} | {{ CompatGeckoMobile("36.0") }} | {{CompatNo}} | 25 | 9 |
| Symbol.iterator (@@iterator) | {{CompatNo}} | {{CompatChrome(38)}} | {{ CompatGeckoMobile("36.0") }} | {{CompatNo}} | 25 | 9 |
| Symbol.unscopables (@@unscopables) | {{CompatNo}} | {{CompatChrome(38)}} | {{ CompatGeckoMobile("48.0") }} | {{CompatNo}} | 25 | 9 |
| Symbol.match (@@match) | {{CompatNo}} | {{CompatNo}} | {{ CompatGeckoMobile("40.0") }} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
| Symbol.species (@@species) | {{CompatNo}} | {{CompatNo}} | {{ CompatGeckoMobile("41.0") }} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
| Symbol.toPrimitive (@@toPrimitive) | {{CompatNo}} | {{CompatNo}} | {{ CompatGeckoMobile("44.0") }} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
| Symbol.replace (@@replace) | {{CompatNo}} | {{CompatNo}} | {{ CompatGeckoMobile("48.0") }} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
| Symbol.search (@@search) | {{CompatNo}} | {{CompatNo}} | {{ CompatGeckoMobile("48.0") }} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
| Symbol.split (@@split) | {{CompatNo}} | {{CompatNo}} | {{ CompatGeckoMobile("48.0") }} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
| Other well-known symbols | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
See also
- Glossary: Symbol data type
- {{jsxref("Operators/typeof", "typeof")}}
- Data types and data structures
- "ES6 In Depth: Symbols" on hacks.mozilla.org