---
title: Symbol
slug: Web/JavaScript/Reference/Global_Objects/Symbol
tags:
  - ECMAScript6
  - JavaScript
  - NeedsTranslation
  - Symbol
  - TopicStub
translation_of: Web/JavaScript/Reference/Global_Objects/Symbol
---
<div>{{JSRef}}</div>

<p>A <strong>symbol</strong> is a unique and immutable data type. It may be used as an identifier for object properties. The <em>Symbol object</em> is an implicit object wrapper for the symbol {{Glossary("Primitive", "primitive data type")}}.</p>

<h2 id="Syntax">Syntax</h2>

<pre class="syntaxbox">Symbol(<em>[description]</em>)</pre>

<h3 id="Parameters">Parameters</h3>

<dl>
 <dt><code>description</code> {{optional_inline}}</dt>
 <dd>Optional, string. A description of the symbol which can be used for debugging but not to access the symbol itself.</dd>
</dl>

<h2 id="Description">Description</h2>

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

<pre class="brush: js">var sym1 = Symbol();
var sym2 = Symbol("foo");
var sym3 = Symbol("foo");
</pre>

<p>The above code creates three new symbols. Note that <code>Symbol("foo")</code> does not coerce the string "foo" into a symbol. It creates a new symbol each time:</p>

<pre class="brush: js">Symbol("foo") === Symbol("foo"); // false</pre>

<p>The following syntax with the {{jsxref("Operators/new", "new")}} operator will throw a {{jsxref("TypeError")}}:</p>

<pre class="brush: js">var sym = new Symbol(); // TypeError</pre>

<p>This prevents authors from creating an explicit <code>Symbol</code> 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, <code>new Boolean</code>, <code>new String</code> and <code>new Number</code>).</p>

<p>If you really want to create a <code>Symbol</code> wrapper object, you can use the <code>Object()</code> function:</p>

<pre class="brush: js">var sym = Symbol("foo");
typeof sym;     // "symbol"
var symObj = Object(sym);
typeof symObj;  // "object"
</pre>

<h3 id="Shared_symbols_in_the_global_symbol_registry">Shared symbols in the global symbol registry</h3>

<p>The above syntax using the <code>Symbol()</code> 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.</p>

<h3 id="Finding_symbol_properties_on_objects">Finding symbol properties on objects</h3>

<p>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.</p>

<h2 id="Properties">Properties</h2>

<dl>
 <dt><code>Symbol.length</code></dt>
 <dd>Length property whose value is 0.</dd>
 <dt>{{jsxref("Symbol.prototype")}}</dt>
 <dd>Represents the prototype for the <code>Symbol</code> constructor.</dd>
</dl>

<h3 id="Well-known_symbols">Well-known symbols</h3>

<p>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:</p>

<h4 id="Iteration_symbols">Iteration symbols</h4>

<dl>
 <dt>{{jsxref("Symbol.iterator")}}</dt>
 <dd>A method returning the default iterator for an object. Used by <a href="/en-US/docs/Web/JavaScript/Reference/Statements/for...of"><code>for...of</code></a>.</dd>
</dl>

<h4 id="Regular_expression_symbols">Regular expression symbols</h4>

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

<h4 id="Other_symbols">Other symbols</h4>

<dl>
 <dt>{{jsxref("Symbol.hasInstance")}}</dt>
 <dd>A method determining if a constructor object recognizes an object as its instance. Used by {{jsxref("Operators/instanceof", "instanceof")}}.</dd>
 <dt>{{jsxref("Symbol.isConcatSpreadable")}}</dt>
 <dd>A Boolean value indicating if an object should be flattened to its array elements. Used by {{jsxref("Array.prototype.concat()")}}.</dd>
 <dt>{{jsxref("Symbol.unscopables")}}</dt>
 <dd>An object value of whose own and inherited property names are excluded from the <code><a href="/en-US/docs/Web/JavaScript/Reference/Statements/with">with</a></code> environment bindings of the associated object.</dd>
 <dt>{{jsxref("Symbol.species")}}</dt>
 <dd>A constructor function that is used to create derived objects.</dd>
 <dt>{{jsxref("Symbol.toPrimitive")}}</dt>
 <dd>A method converting an object to a primitive value.</dd>
 <dt>{{jsxref("Symbol.toStringTag")}}</dt>
 <dd>A string value used for the default description of an object. Used by {{jsxref("Object.prototype.toString()")}}.</dd>
</dl>

<h2 id="Methods">Methods</h2>

<dl>
 <dt>{{jsxref("Symbol.for()", "Symbol.for(key)")}}</dt>
 <dd>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.</dd>
 <dt>{{jsxref("Symbol.keyFor", "Symbol.keyFor(sym)")}}</dt>
 <dd>Retrieves a shared symbol key from the global symbol registry for the given symbol.</dd>
</dl>

<h2 id="Symbol_prototype"><code>Symbol</code> prototype</h2>

<p>All Symbols inherit from {{jsxref("Symbol.prototype")}}.</p>

<h3 id="Properties_2">Properties</h3>

<p>{{page('en-US/Web/JavaScript/Reference/Global_Objects/Symbol/prototype','Properties')}}</p>

<h3 id="Methods_2">Methods</h3>

<p>{{page('en-US/Web/JavaScript/Reference/Global_Objects/Symbol/prototype','Methods')}}</p>

<h2 id="Examples">Examples</h2>

<h3 id="Using_the_typeof_operator_with_symbols">Using the <code>typeof</code> operator with symbols</h3>

<p>The {{jsxref("Operators/typeof", "typeof")}} operator can help you to identify symbols.</p>

<pre class="brush: js">typeof Symbol() === 'symbol'
typeof Symbol('foo') === 'symbol'
typeof Symbol.iterator === 'symbol'
</pre>

<h3 id="Symbol_type_conversions">Symbol type conversions</h3>

<p>Some things to note when working with type conversion of symbols.</p>

<ul>
 <li>When trying to convert a symbol to a number, a {{jsxref("TypeError")}} will be thrown<br>
  (e.g. <code>+sym</code> or <code>sym | 0</code>).</li>
 <li>When using loose equality, <code>Object(sym) == sym</code> returns <code>true.</code></li>
 <li><code>Symbol("foo") + "bar" </code>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.</li>
 <li>The <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#String_conversion">"safer" <code>String(sym)</code> conversion</a> works like a call to {{jsxref("Symbol.prototype.toString()")}} with symbols, but note that <code>new String(sym)</code> will throw.</li>
</ul>

<h3 id="Symbols_and_for...in_iteration">Symbols and <code>for...in</code> iteration</h3>

<p>Symbols are not enumerable in <a href="/en-US/docs/Web/JavaScript/Reference/Statements/for...in"><code>for...in</code></a> iterations. In addition, {{jsxref("Object.getOwnPropertyNames()")}} will not return symbol object properties, however, you can use {{jsxref("Object.getOwnPropertySymbols()")}} to get these.</p>

<pre class="brush: js">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"
}</pre>

<h3 id="Symbols_and_JSON.stringify()">Symbols and <code>JSON.stringify()</code></h3>

<p>Symbol-keyed properties will be completely ignored when using <code>JSON.stringify()</code>:</p>

<pre class="brush: js">JSON.stringify({[Symbol("foo")]: "foo"});
// '{}'</pre>

<p>For more details, see {{jsxref("JSON.stringify()")}}.</p>

<h3 id="Symbol_wrapper_objects_as_property_keys">Symbol wrapper objects as property keys</h3>

<p>When a Symbol wrapper object is used as a property key, this object will be coerced to its wrapped symbol:</p>

<pre class="brush: js">var sym = Symbol("foo");
var obj = {[sym]: 1};
obj[sym];            // 1
obj[Object(sym)];    // still 1
</pre>

<h2 id="Specifications">Specifications</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
  <tr>
   <td>{{SpecName('ES6', '#sec-symbol-objects', 'Symbol')}}</td>
   <td>{{Spec2('ES6')}}</td>
   <td>Initial definition</td>
  </tr>
  <tr>
   <td>{{SpecName('ESDraft', '#sec-symbol-objects', 'Symbol')}}</td>
   <td>{{Spec2('ESDraft')}}</td>
   <td> </td>
  </tr>
 </tbody>
</table>

<h2 id="Browser_compatibility">Browser compatibility</h2>

<p>{{CompatibilityTable}}</p>

<div id="compat-desktop">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Chrome</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>{{CompatChrome(38)}}</td>
   <td>{{CompatGeckoDesktop(36)}}</td>
   <td>{{CompatNo}}</td>
   <td>25</td>
   <td>9</td>
  </tr>
  <tr>
   <td>Symbol.iterator (@@iterator)</td>
   <td>{{CompatChrome(38)}}</td>
   <td>{{CompatGeckoDesktop(36)}}</td>
   <td>{{CompatNo}}</td>
   <td>25</td>
   <td>9</td>
  </tr>
  <tr>
   <td>Symbol.unscopables (@@unscopables)</td>
   <td>{{CompatChrome(38)}}</td>
   <td>{{CompatGeckoDesktop(48)}}</td>
   <td>{{CompatNo}}</td>
   <td>25</td>
   <td>9</td>
  </tr>
  <tr>
   <td>Symbol.match (@@match)</td>
   <td>{{CompatChrome(50)}}</td>
   <td>{{CompatGeckoDesktop(40)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.species (@@species)</td>
   <td>{{CompatChrome(51)}}</td>
   <td>{{CompatGeckoDesktop(41)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.toPrimitive (@@toPrimitive)</td>
   <td>{{CompatChrome(48)}}</td>
   <td>{{CompatGeckoDesktop(44)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.replace (@@replace)</td>
   <td>{{CompatChrome(50)}}</td>
   <td>{{CompatGeckoDesktop(48)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.search (@@search)</td>
   <td>{{CompatChrome(50)}}</td>
   <td>{{CompatGeckoDesktop(48)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.split (@@split)</td>
   <td>{{CompatChrome(50)}}</td>
   <td>{{CompatGeckoDesktop(48)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.isConcatSpreadable (@@isconcatspreadable)</td>
   <td>{{CompatChrome(48)}}</td>
   <td>{{CompatGeckoDesktop(48)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.hasInstance (@@hasInstance)</td>
   <td>{{CompatChrome(51)}}</td>
   <td>{{CompatGeckoDesktop(50)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.toStringTag (@@toStringTag)</td>
   <td>{{CompatChrome(49)}}</td>
   <td>{{CompatGeckoDesktop(51)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
 </tbody>
</table>
</div>

<div id="compat-mobile">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Android</th>
   <th>Chrome for Android</th>
   <th>Firefox Mobile (Gecko)</th>
   <th>IE Mobile</th>
   <th>Opera Mobile</th>
   <th>Safari Mobile</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatChrome(38)}}</td>
   <td>{{CompatGeckoMobile(36)}}</td>
   <td>{{CompatNo}}</td>
   <td>25</td>
   <td>9</td>
  </tr>
  <tr>
   <td>Symbol.iterator (@@iterator)</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatChrome(38)}}</td>
   <td>{{CompatGeckoMobile(36)}}</td>
   <td>{{CompatNo}}</td>
   <td>25</td>
   <td>9</td>
  </tr>
  <tr>
   <td>Symbol.unscopables (@@unscopables)</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatChrome(38)}}</td>
   <td>{{CompatGeckoMobile(48)}}</td>
   <td>{{CompatNo}}</td>
   <td>25</td>
   <td>9</td>
  </tr>
  <tr>
   <td>Symbol.match (@@match)</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatGeckoMobile(40)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.species (@@species)</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatGeckoMobile(41)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.toPrimitive (@@toPrimitive)</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatGeckoMobile(44)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.replace (@@replace)</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatGeckoMobile(48)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.search (@@search)</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatGeckoMobile(48)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.split (@@split)</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatGeckoMobile(48)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.isConcatSpreadable (@@isconcatspreadable)</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatGeckoMobile(48)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.hasInstance (@@hasInstance)</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatGeckoMobile(50)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Symbol.toStringTag (@@toStringTag)</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatGeckoMobile(51)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
 </tbody>
</table>
</div>

<h2 id="See_also">See also</h2>

<ul>
 <li><a href="/en-US/docs/Glossary/Symbol">Glossary: Symbol data type</a></li>
 <li>{{jsxref("Operators/typeof", "typeof")}}</li>
 <li><a href="/en-US/docs/Web/JavaScript/Data_structures">Data types and data structures</a></li>
 <li><a href="https://hacks.mozilla.org/2015/06/es6-in-depth-symbols/">"ES6 In Depth: Symbols" on hacks.mozilla.org</a></li>
</ul>