Symbols

JavaScript's unique identifier primitive — Symbol(), well-known symbols, Symbol.iterator, Symbol.for, and using symbols as private-ish object keys.

What it is, in plain English: A Symbol is a primitive value that is guaranteed to be unique — no two Symbols are ever equal, even if created with the same description. Symbols are used as object property keys that can't accidentally collide with other keys. Well-known Symbols (Symbol.iterator, Symbol.toPrimitive, Symbol.hasInstance...) let you hook into JavaScript's built-in behaviours.

Unique keys that never collide

JavaScript objects can have properties keyed by strings or Symbols. String keys can clash — if two pieces of code both add a "id" property, one overwrites the other. A Symbol is guaranteed unique — even two Symbols created with the same description are different values.

Creating Symbols

const sym1 = Symbol("description");   // the description is just for debugging
const sym2 = Symbol("description");

console.log(sym1 === sym2);   // false — ALWAYS different
console.log(typeof sym1);     // "symbol"
console.log(sym1.description); // "description" — the label you gave it
console.log(sym1.toString());  // "Symbol(description)"

// You cannot new Symbol() — it's not a constructor:
// new Symbol()  // TypeError: Symbol is not a constructor

Using Symbols as object keys

const SECRET = Symbol("secret");
const ID     = Symbol("id");

const user = {
  name:     "Alice",
  [SECRET]: "password123",   // computed property syntax for Symbol keys
  [ID]:     42,
};

// Access with the Symbol reference:
console.log(user[SECRET]);   // "password123"
console.log(user[ID]);       // 42
console.log(user.name);      // "Alice"

// Symbol keys are hidden from normal enumeration:
console.log(Object.keys(user));       // ["name"] — no symbols
console.log(JSON.stringify(user));    // {"name":"Alice"} — symbols dropped

// You need the actual Symbol reference to access it:
// user["secret"]  → undefined (that's a string key, not the Symbol)

The main uses of Symbols

// 1. Unique constants (no collision with other code):
const STATUS_PENDING  = Symbol("pending");
const STATUS_DONE     = Symbol("done");
const STATUS_FAILED   = Symbol("failed");

function process(task) {
  task.status = STATUS_PENDING;
  // ... do work ...
  task.status = STATUS_DONE;
}

// 2. Adding metadata to objects you don't own:
const META = Symbol("meta");
const thirdPartyObject = { data: [1, 2, 3] };
thirdPartyObject[META] = { addedAt: Date.now() };  // won't clash with any existing key

// 3. The global registry — share a Symbol across modules:
const shared1 = Symbol.for("app.user.id");
const shared2 = Symbol.for("app.user.id");
console.log(shared1 === shared2);  // true — same symbol from registry

Try It Yourself

// Every Symbol() call creates a unique value
const s1 = Symbol("my symbol");
const s2 = Symbol("my symbol");

console.log(s1 === s2);           // false — always unique!
console.log(typeof s1);           // "symbol"
console.log(s1.toString());       // "Symbol(my symbol)"
console.log(s1.description);      // "my symbol"

// Use as object keys — won't clash with string keys
const ID   = Symbol("id");
const TYPE = Symbol("type");

const user = {
  name: "Alice",
  [ID]:   42,         // Symbol key — uses computed property syntax
  [TYPE]: "admin",
};

console.log(user.name);    // "Alice"
console.log(user[ID]);     // 42
console.log(user[TYPE]);   // "admin"

// Symbol keys are invisible to most iteration:
console.log(Object.keys(user));    // ["name"] — no symbols!
console.log(JSON.stringify(user)); // {"name":"Alice"} — symbols dropped

// Get symbol keys explicitly:
console.log(Object.getOwnPropertySymbols(user)); // [Symbol(id), Symbol(type)]

// Global Symbol registry — share symbols across files:
const globalSym1 = Symbol.for("shared");
const globalSym2 = Symbol.for("shared");
console.log(globalSym1 === globalSym2);  // true — same registry entry

// Well-known symbol: Symbol.iterator
class Range {
  constructor(start, end) { this.start = start; this.end = end; }
  [Symbol.iterator]() {
    let current = this.start;
    const end = this.end;
    return { next() { return current <= end
      ? { value: current++, done: false }
      : { value: undefined, done: true }; } };
  }
}
console.log([...new Range(1, 5)]);  // [1, 2, 3, 4, 5]

Well-known symbols — hooking into JS built-in behaviour

JavaScript has a set of built-in Symbols called well-known symbols. By adding these as methods on your objects, you customise how JavaScript's operators and built-in functions treat them.

Symbol.iterator — make anything iterable

class NumberRange {
  constructor(start, end, step = 1) {
    this.start = start;
    this.end   = end;
    this.step  = step;
  }

  [Symbol.iterator]() {
    let current = this.start;
    const { end, step } = this;
    return {
      next() {
        if (current <= end) {
          const value = current;
          current += step;
          return { value, done: false };
        }
        return { value: undefined, done: true };
      }
    };
  }
}

const evens = new NumberRange(2, 10, 2);
console.log([...evens]);           // [2, 4, 6, 8, 10]
for (const n of new NumberRange(1, 5)) console.log(n);  // 1 2 3 4 5

Symbol.toPrimitive — control type conversion

class Temperature {
  constructor(celsius) { this.celsius = celsius; }

  [Symbol.toPrimitive](hint) {
    if (hint === "number") return this.celsius;
    if (hint === "string") return `${this.celsius}°C`;
    return this.celsius;  // "default" hint
  }
}

const t = new Temperature(37);
console.log(+t);          // 37      (number hint)
console.log(`${t}`);      // "37°C"  (string hint)
console.log(t + 0);       // 37      (default hint)

Symbol.hasInstance — customise instanceof

class Even {
  static [Symbol.hasInstance](num) {
    return typeof num === "number" && num % 2 === 0;
  }
}

console.log(2 instanceof Even);   // true
console.log(3 instanceof Even);   // false

All well-known symbols

Symbol.iterator       // for...of, spread, destructuring
Symbol.asyncIterator  // for await...of
Symbol.toPrimitive    // +, template literals, comparisons
Symbol.toStringTag    // Object.prototype.toString() tag
Symbol.hasInstance    // instanceof
Symbol.isConcatSpreadable  // Array.prototype.concat
Symbol.species        // constructor for derived objects (Array, Map, Set)
Symbol.match          // String.prototype.match, startsWith
Symbol.replace        // String.prototype.replace
Symbol.search         // String.prototype.search
Symbol.split          // String.prototype.split
Symbol.unscopables    // with statement exclusions

Symbol internals and the global registry

Symbols in the spec (ECMA-262 §20.4)

Symbols are a primitive type — they pass the IsSymbol abstract operation check and have type tag "symbol" from typeof. Symbol values are not coercible to string via implicit conversion (only .toString() or .description) — attempting string concatenation throws a TypeError. Each Symbol has an internal [[Description]] slot and an internal [[SymbolData]] slot. The Symbol wrapper object (from Object(Symbol())) wraps the primitive.

The global Symbol registry

Symbol.for(key) and Symbol.keyFor(sym) access a global registry that persists across realms (iframes, workers). Regular Symbol() is never in the registry — only Symbol.for() entries are:

const s = Symbol("local");         // not in registry
const g = Symbol.for("global");    // in registry

Symbol.keyFor(s);   // undefined — not registered
Symbol.keyFor(g);   // "global"

// Cross-realm: the same Symbol.for("key") in an iframe and parent window
// returns the same Symbol — they share the global registry

Symbol.toStringTag — customising Object.prototype.toString

class MyCollection {
  get [Symbol.toStringTag]() { return "MyCollection"; }
}

const c = new MyCollection();
console.log(Object.prototype.toString.call(c)); // "[object MyCollection]"
// This is how built-ins work:
// Map:  [object Map], Set: [object Set], Promise: [object Promise]
// Used for reliable type detection across realms

Official Sources

The Codex links only to official documentation and the ECMAScript specification. No third-party tutorials.