mozilla
Your Search Results

    Symbol

    This is an experimental technology, part of the ECMAScript 6 (Harmony) proposal.
    Because this technology's specification has not stabilized, check the compatibility table for usage in various browsers. Also note that the syntax and behavior of an experimental technology is subject to change in future version of browsers as the spec changes.

    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 primitive data type.

    Syntax

    Symbol([description])

    Parameters

    description Optional
    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 simply 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. Creating an explicit wrapper object around primitive data types is no longer supported starting with ECMAScript 6. However, existing primitive wrapper objects like new Boolean, new String and new Number can still be created for legacy reasons.

    And if you really want to create a Symbol wrapper object, you can use 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 in a global scope-like environment, 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.

    Properties

    Symbol.length
    Length property whose value is 1.
    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

    Symbol.iterator
    A method returning the default iterator for an object. Used by for...of.

    Regular expression symbols

    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.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().

    Other symbols

    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.unscopables
    An Array of string values that are property values. These are excluded from the with environment bindings of the associated objects.
    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().

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

    Symbol prototype

    All Symbols inherit from Symbol.prototype.

    Properties

    Symbol.prototype.constructor
    Returns the function that created an instance's prototype. This is the Symbol function by default.

    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 of 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.

    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 visible 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
    

    Specifications

    Specification Status Comment
    ECMAScript 6 (ECMA-262)
    The definition of 'Symbol' in that specification.
    Release Candidate Initial definition.

    Browser compatibility

    Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
    Basic support 38 36.0 (36.0) Not supported 25 Not supported
    Symbol.iterator (@@iterator) 38 36.0 (36.0) Not supported 25 Not supported
    Symbol.unscopables (@@unscopables) 38 Not supported Not supported 25 Not supported
    Symbol.match (@@match) Not supported 40.0 (40.0) Not supported Not supported Not supported
    Symbol.species (@@species) Not supported 41.0 (41.0) Not supported Not supported Not supported
    Other well-known symbols Not supported Not supported Not supported Not supported Not supported
    Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
    Basic support Not supported 38 36.0 (36.0) Not supported 25 Not supported
    Symbol.iterator (@@iterator) Not supported 38 36.0 (36.0) Not supported 25 Not supported
    Symbol.unscopables (@@unscopables) Not supported 38 Not supported Not supported 25 Not supported
    Symbol.match (@@match) Not supported Not supported 40.0 (40.0) Not supported Not supported Not supported
    Symbol.species (@@species) Not supported Not supported 41.0 (41.0) Not supported Not supported Not supported
    Other well-known symbols Not supported Not supported Not supported Not supported Not supported Not supported

    See also

    Document Tags and Contributors

    Contributors to this page: ferno, tregagnon, fscholz, ziyunfei, phistuck, cvrebert, arai
    Last updated by: arai,