JavaScript 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:
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);
Try it Yourself »
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;
Try it Yourself »
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:
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
Try it Yourself »
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
Try it Yourself »
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);
Try it Yourself »
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);
Try it Yourself »
The result is true.
Well-Known Symbols
JavaScript provides built-in Symbols called well-known Symbols.
These Symbols control JavaScript behaviors.
Examples:
Symbol.iteratorSymbol.asyncIteratorSymbol.toStringTagSymbol.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
Try it Yourself »
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:
| Chrome 51 |
Edge 15 |
Firefox 54 |
Safari 10 |
Opera 38 |
| May 2016 | Apr 2017 | Jun 2017 | Sep 2016 | Jun 2016 |
