JS Symbols

Unique Values

A Symbol represents a unique identifier.

Every Symbol value is unique, even if they have the same description.

A Symbol is a hidden identifier that no code can accidentally access.

Creating Symbols

Use Symbol() to create a Symbol:

Example

const id1 = Symbol();

const id2 = Symbol();

The two Symbols are different:

Example

const id1 = Symbol();

const id2 = Symbol();

let result = (id1 === id2);

Note: The result is false. Every Symbol has a unique value.

Symbol Descriptions

You can add a description to a Symbol:

Example

const id = Symbol("id");

The description is only for debugging and readability.

It does not make the Symbol unique.

Example

const id1 = Symbol("id");

const id2 = Symbol("id");

let result = (id1 === id2);

Note: The result is still false. Symbols are always unique. If you create two symbols with the same description they will have different values: Symbol("id") == Symbol("id"); // false

Using Symbols as Object Keys

Symbols are often used as object property keys.

This lets you create hidden or unique properties.

Example

const id = Symbol("id");

const person = {

  firstName: "John",

  lastName: "Doe"

};

person[id] = 123;

The Symbol Type

A JavaScript Symbol is a primitive data type just like Number, String, or Boolean.

The JavaScript type of a Symbol is symbol:

Example

const id = Symbol("id");

let type = typeof id;

Hidden Identifiers

A Symbol represents a unique "hidden" identifier that no code can accidentally access.

For instance, if different programmers want to add a person.id property to a person object belonging to a third-party code, they could mix each others values.

Using Symbol() to create a unique identifiers, solves this problem:

Example

const person = {

  firstName: "John",

  lastName: "Doe",

  age: 50,

  eyeColor: "blue"

};

let id = Symbol('id');

person[id] = 140353;

// Now person[id] = 140353

// but person.id is still undefined

Symbols are Not Included in for...in

Symbol properties are ignored by for...in loops:

Example

const id = Symbol("id");

const person = {

  firstName: "John",

  lastName: "Doe"

};

person[id] = 123;

let text = "";

for (let x in person) {

  text += x + "<br>";

}

// Display text

Note: The Symbol property is not displayed.

Symbols are Not Included in JSON

Symbol properties are ignored by JSON.stringify():

Example

const id = Symbol("id");

const person = {

  name: "John"

};

person[id] = 123;

let text = JSON.stringify(person);

Global Symbols

JavaScript has a global Symbol registry.

Use Symbol.for() to create or reuse a global Symbol:

Example

const id1 = Symbol.for("id");

const id2 = Symbol.for("id");

let result = (id1 === id2);

Note: The result is true.

Well-Known Symbols

JavaScript provides built-in Symbols called well-known Symbols.

These Symbols control JavaScript behaviors.

Examples:

• Symbol.iterator
• Symbol.asyncIterator
• Symbol.toStringTag
• Symbol.toPrimitive

Symbol.iterator

The Symbol.iterator Symbol defines an iterable object.

This makes objects work with loops like for...of.

Example

const myObject = {

  data: ["A", "B", "C"],

  [Symbol.iterator]() {

    let index = 0;

    let data = this.data;

    return {

      next() {

        if (index < data.length) {

          return {value:data[index++], done:false};

        } else {

          return {done:true};

        }

      }

    };

  }

};

let text = "";

for (const x of myObject) {

  text += x + "<br>";

}

// Display text

When to Use Symbols

Use Symbols when you need:

• Unique object property names
• Hidden object properties
• Custom iterable objects
• Special object behavior

When NOT to Use Symbols

Symbols are not commonly used in everyday JavaScript code.

Do not use Symbols unless you need unique property keys or advanced object behavior.

For normal object properties, use strings names instead.

Browser Support

Symbol is an ES6 feature.

ES6 is fully supported in all modern browsers since June 2017: