A Symbol is a JavaScript value that is always unique. You create one by calling Symbol(), and no other symbol is ever equal to it, not even one made with the same description. Symbols are mostly used as property keys that cannot clash with any other key.
Symbol is a primitive type, like strings and numbers, so typeof Symbol() is "symbol". You never use new with it. JavaScript also keeps a shared list of symbols, the global symbol registry, which you reach with Symbol.for() and Symbol.keyFor().
The text in Symbol("id") helps you read logs. It does not make the symbol equal to anything else, so Symbol("id") === Symbol("id") is false.
Syntax
JavaScript Syntax
Create a symbol, use it as a property key, and get a shared symbol from the registry:
JavaScript
const id = Symbol("id"); // a new unique symbol
const user = { name: "Ana" };
user[id] = 101; // use it as a property key
console.log(user[id]); // 101
console.log(typeof id); // "symbol"
const shared = Symbol.for("app.id"); // the same symbol for the same key
console.log(Symbol.keyFor(shared)); // "app.id"
Reference
Core Ideas
Ideas every Symbol tutorial in this series builds on:
Idea
Example
Remember
Symbol()
const id = Symbol("id")
Creates a new unique symbol every time it is called
Description
id.description
The optional label; it does not make symbols equal
Symbol key
obj[id] = 101
A property that normal loops and JSON skip
Global registry
Symbol.for("app.id")
A shared list: the same key gives the same symbol
Symbol.keyFor()
Symbol.keyFor(sym)
Gives the registry key, or undefined for other symbols
Well-known symbols
Symbol.iterator
Built-in symbols that let objects join language features
Conversion
String(id)
Symbols never turn into text or numbers by themselves
Compare
Symbol vs a String Key
A symbol can be used wherever a string key is used. These four kinds of keys behave differently:
Key
How you get it
Same every time?
"id" (string)
Write the text
Yes: the same text is the same key
Symbol("id")
Call Symbol()
No: a new symbol on every call
Symbol.for("id")
Call Symbol.for()
Yes: shared through the global registry
Symbol.iterator
Built in
Yes: one symbol for all code
Use a string when everyone should be able to find the key by name. Use Symbol() when the key must belong to your code only. Example 2 shows how symbol keys stay hidden.
Behavior
How Symbols Work
A symbol is a primitive
Symbols are copied by value like numbers and strings, and typeof says "symbol". They are not objects, which is why new Symbol() throws a TypeError.
Every call makes a new one
Symbol("id") never returns an old symbol. Two symbols with the same description are different values, so they can never overwrite each other as property keys.
Loops and JSON skip symbol keys
Object.keys(), for...in and JSON.stringify() ignore properties whose key is a symbol. To list them, use Object.getOwnPropertySymbols().
No automatic conversion
A symbol never becomes text or a number by itself. "x" + symbol and +symbol throw a TypeError. Convert on purpose with String(symbol) or symbol.description.
The registry shares symbols
Symbol.for(key) looks the key up in one list that all your code shares. The first call creates the symbol, and every later call with the same key returns it.
Practice
Real-Life Uses
You will meet symbols in a few special places:
Use
How a symbol helps
Hidden metadata
Attach an ID or a flag to an object without showing up in Object.keys() or in JSON.
Constants that never clash
Use Symbol("red") as an enum-like value, so no other value can ever be equal to it by accident.
Avoiding key clashes
A library can add its own property to your object without overwriting a property that you already have.
Built-in protocols
Well-known symbols such as Symbol.iterator let your own objects work with for...of and the spread syntax.
Code
JavaScript Examples
Three short programs. Each one prints plain text that is the same every time you run it.
Example 1 — Create Symbols and Compare Them
Create symbols with and without the registry, compare them, and break the new rule on purpose.
Define the key. A method named [Symbol.iterator]() tells JavaScript how to walk through the object. It returns an object with a next() function that counts down from start.
The language uses it.for...of and [...countdown] both call that method, so the same object can be looped and spread, giving 3, 2, 1.
Built-in, not registered.Symbol.iterator has a description, but Symbol.keyFor() returns undefined, because well-known symbols are not in the global registry.
Continue
Symbol Methods
The Symbol object has two static methods, and every symbol has three instance methods. Each one has its own tutorial:
A Symbol is a primitive value that is always unique. You create one with Symbol("description"), and it is never equal to any other symbol. Symbols are mostly used as property keys that cannot clash with other keys.
Because each call to Symbol() creates a brand new symbol. The text only describes the symbol and does not make two symbols equal. If you want the same symbol for the same text, use Symbol.for("id").
Symbols are primitive values and not objects, so new Symbol() throws a TypeError. Call Symbol("description") as a normal function. If you really need a wrapper object, use Object(symbol).
No. They are hidden from Object.keys(), for...in and JSON.stringify(), but Object.getOwnPropertySymbols() lists them, so anyone can find them. Use symbols to avoid clashes and accidents. For real privacy use a private field such as #secret in a class.
Use a symbol when a key or constant must not clash with any other value, such as hidden metadata, enum-like constants, or protocol keys like Symbol.iterator. For ordinary data, a plain string key is simpler and easier to read in JSON.