Symbols — Well-Known Symbols, Hidden Properties & More

Symbols are the 7th primitive type in JavaScript. They solve a concrete problem: guaranteed-unique property keys.

Before Symbols, if two libraries both added a property called "id" to the same object, one would silently overwrite the other. The workaround was ugly prefixed strings like "__myLib_id_abc123". Symbols fix this: Symbol("id") is never equal to another Symbol("id"), so collisions are impossible.

Beyond unique keys, Symbols also let you hook into JavaScript's internal protocols through well-known symbols — making objects iterable, controlling type coercion, customizing instanceof, and more. This article covers both aspects.

Prerequisites: JS Foundations #4 — Prototypes

1. Creating Symbols — Guaranteed Unique

Every Symbol() call returns a completely unique value — even if you give them the same description:

2. Symbols as Object Keys — Hidden Properties

Symbol-keyed properties don't appear in Object.keys(), for...in, or JSON.stringify():

This makes them useful for "soft" private properties — not truly private (still accessible via getOwnPropertySymbols), but hidden from casual iteration.

3. Global Symbol Registry — Symbol.for() and Symbol.keyFor()

The global symbol registry lets you share symbols across realms/frames:

4. Well-Known Symbols — Hooking Into JavaScript

JavaScript uses well-known symbols to let you customize object behavior:

Symbol.iterator — Make Objects Iterable

Symbol.toPrimitive — Control Type Coercion

Symbol.toStringTag — Custom Object.prototype.toString()

Symbol.hasInstance — Custom instanceof

5. All Well-Known Symbols at a Glance

Key Takeaways

• Symbols are unique — Symbol("x") !== Symbol("x"). Use them for non-colliding keys.
• Symbol-keyed properties are hidden from Object.keys(), for...in, and JSON.stringify().
• Use Symbol.for("key") for shared global symbols; Symbol.keyFor() to retrieve the key.
• Well-known symbols let you hook into JavaScript's built-in protocols — iterator, coercion, instanceof, string tags.
• Symbol.toPrimitive is the most powerful control over how your object behaves in +, ${}, and numeric contexts.

Next: Proxy & Reflect — Validation, Observables & Traps — intercept fundamental operations with all 13 proxy traps.