Symbols
Unique, immutable identifiers used for hidden properties and well-known iteration protocols.
What you'll learn
- What a Symbol is and why every Symbol() is unique
- Using Symbols as object keys to avoid collisions
- Symbols are not enumerated by for...in or Object.keys
- Shared Symbols with Symbol.for and Symbol.keyFor
- Well-known Symbols like Symbol.iterator and Symbol.toPrimitive
Concept
Unique Identifiers
A Symbol is a primitive type introduced in ES6. Every call to Symbol() produces a completely unique value — even Symbol("foo") === Symbol("foo") is false. The optional description is just a label for debugging; it does not affect identity. This uniqueness makes Symbols ideal as property keys that will never accidentally collide with another key.
Symbols as Object Keys
You can use a Symbol as a property key in an object: obj[mySymbol] = value. Symbol-keyed properties are hidden from normal enumeration — for...in, Object.keys(), and JSON.stringify() all skip them. This lets you attach metadata to an object without it appearing in serialization or iteration. To access Symbol keys explicitly, use Object.getOwnPropertySymbols().
Shared Symbols
Symbol.for("key") returns a global, shared Symbol: calling it again with the same key returns the same Symbol. This is the global Symbol registry. Symbol.keyFor(sym) retrieves the key for a shared Symbol. Use Symbol.for when you need cross-module sharing (e.g., a library-defined extension point); use Symbol() for private, local keys.
Well-Known Symbols
JavaScript defines a set of well-known Symbols on the Symbol object that hook into language behavior. Symbol.iterator defines how for...of and the spread operator iterate an object. Symbol.toPrimitive controls conversion to number/string/boolean. Symbol.hasInstance customizes instanceof. Symbol.toStringTag improves Object.prototype.toString output. Implementing these on your objects lets you integrate deeply with the language.
Practical Use
Symbols are not an everyday tool, but they appear in library internals and protocol definitions. If you are building a framework, Symbols let you define extension points that users cannot accidentally overwrite. If you are consuming APIs, you will encounter them on iterators and other built-in protocols. Knowing they exist helps you read framework source code and understand why certain properties do not show up in Object.keys().
Example
// Every Symbol() is unique, even with the same description
const s1 = Symbol("id");
const s2 = Symbol("id");
console.log(s1 === s2); // false
console.log(s1.description); // "id" — just a debug label
// Symbols as hidden object keys
const hidden = Symbol("private");
const obj = {
name: "Ada",
[hidden]: "secret metadata",
};
console.log(Object.keys(obj)); // ["name"] — Symbol key is hidden
console.log(JSON.stringify(obj)); // {"name":"Ada"} — not serialized
console.log(obj[hidden]); // "secret metadata" — accessible directly
console.log(Object.getOwnPropertySymbols(obj)); // [Symbol(private)]
// Shared Symbols across modules via the global registry
const SHARED = Symbol.for("app.shared");
const objA = { [SHARED]: "from module A" };
const sameSymbol = Symbol.for("app.shared");
console.log(objA[sameSymbol]); // "from module A"
console.log(Symbol.keyFor(SHARED)); // "app.shared"
// Well-known Symbol: customize toString output
class Color {
constructor(hex) {
this.hex = hex;
}
get [Symbol.toStringTag]() {
return "Color";
}
}
console.log(Object.prototype.toString.call(new Color("#fff"))); // "[object Color]"
// Well-known Symbol: control primitive conversion
const temp = {
value: 42,
[Symbol.toPrimitive](hint) {
if (hint === "number") return this.value;
if (hint === "string") return `${this.value}°`;
return this.value;
},
};
console.log(+temp); // 42 (number hint)
console.log(`${temp}`); // "42°" (string hint)
Shows Symbol uniqueness, hidden keys invisible to Object.keys and JSON, the global registry with Symbol.for, toStringTag customization, and toPrimitive for controlling +temp and string interpolation.
Try it
- JSON Formatter
See how Symbol-keyed properties are skipped by JSON.stringify.
- JSON Tree Viewer
Inspect objects and notice Symbol properties are not enumerated.
Common mistakes
The mistake
Expecting Symbol('x') === Symbol('x') to be true
The fix
Symbol() always returns a unique value. The description is only a debug label. For shared Symbols across modules, use Symbol.for('x') which returns the same Symbol for the same key from the global registry.
The mistake
Looking for Symbol-keyed properties with Object.keys or for...in
The fix
Symbol keys are hidden from Object.keys, for...in, and JSON.stringify. Use Object.getOwnPropertySymbols(obj) to retrieve them, or Reflect.ownKeys for both string and Symbol keys.
Related Resources
Related Cheatsheets
- JavaScript Cheatsheet
Symbol creation, shared registry, and well-known Symbols.
Look up unfamiliar terms
A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.
Build real projects
Apply what you learned by building guided projects with starter code and solutions.
Decode error messages
Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.