JavaScript Symbols

A Symbol is a primitive value in JavaScript that is guaranteed to be unique every time you create one. Symbols exist mainly to solve one problem: giving objects property keys that will never accidentally collide with another key, even one with the exact same description. They power some of JavaScript’s most important internal behaviors, like how for...of loops know an object is iterable.

Overview / How Symbols Work

Before symbols, JavaScript objects could only use strings as property keys (numbers get coerced to strings). This meant that if two independent pieces of code both wanted to attach metadata to the same object using a key like "id" or "type", they risked silently overwriting each other. Symbols fix this by introducing a seventh primitive type — alongside string, number, boolean, null, undefined, and bigint — whose values are always unique.

You create a symbol by calling the Symbol() function (never with new). Each call returns a brand-new, unique value, even if you pass the same description string:

Symbol('id') !== Symbol('id')

Internally, the JavaScript engine treats every symbol as an opaque, unforgeable token. Two symbols are only ever equal (===) if they refer to the exact same value in memory — there is no way to construct a symbol that matches an existing one, except through the global symbol registry (covered below). This uniqueness is what makes symbols safe as object keys: you can add a symbol-keyed property to any object, including objects you don’t control, without any risk of clashing with existing or future string keys.

A second major role of symbols is powering JavaScript’s well-known symbols — special built-in symbols like Symbol.iterator, Symbol.toPrimitive, and Symbol.hasInstance that let your own objects hook into language-level behavior such as for...of loops, spread syntax, type coercion, and instanceof checks.

Symbols are also intentionally excluded from most everyday enumeration mechanisms. They do not show up in for...in loops, Object.keys(), Object.values(), Object.entries(), or JSON.stringify(). This makes them useful for attaching “quasi-private” metadata to an object without cluttering its normal, visible property list — though, as you’ll see in Common Mistakes, this is obscurity, not real privacy.

Syntax

const sym = Symbol(description);
const globalSym = Symbol.for(key);

Symbol(description) — creates a new, unique symbol. description is optional and purely for debugging/logging; it has no effect on uniqueness.
Symbol.for(key) — looks up (or creates) a symbol in a global registry shared across your entire program (and even across iframes/realms). Calling it twice with the same string key always returns the exact same symbol.
Symbol.keyFor(sym) — returns the registry key for a symbol created with Symbol.for(), or undefined if the symbol isn’t in the registry.
sym.description — a read-only property returning the description string (or undefined if none was given).
sym.toString() — returns a string like "Symbol(description)". Useful because symbols cannot be implicitly converted to strings.
Note: new Symbol() is invalid and throws a TypeError — Symbol is a function, not a constructor.

Examples

Example 1: Basic creation and uniqueness

const sym1 = Symbol('id');
const sym2 = Symbol('id');

console.log(sym1 === sym2);
console.log(sym1.toString());
console.log(sym1.description);
console.log(typeof sym1);

Output:

false
Symbol(id)
id
symbol

Even though both symbols share the description 'id', they are completely distinct values. The description is only a human-readable label; it plays no role in equality.

Example 2: Using a symbol as a collision-proof object key

const nameSymbol = Symbol('name');

const user = {
  name: 'Alice',
  [nameSymbol]: 'Hidden Alice'
};

console.log(user.name);
console.log(user[nameSymbol]);
console.log(Object.keys(user));
console.log(JSON.stringify(user));
console.log(Object.getOwnPropertySymbols(user));

Output:

Alice
Hidden Alice
[ 'name' ]
{"name":"Alice"}
[ Symbol(name) ]

The object has two completely independent name-ish properties: the ordinary string key "name" and the symbol key stored in nameSymbol. They never collide. Notice that Object.keys() and JSON.stringify() both ignore the symbol-keyed property entirely — you need Object.getOwnPropertySymbols() (or Reflect.ownKeys()) to see it.

Example 3: Making a custom object iterable with 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() {
        if (current <= end) {
          return { value: current++, done: false };
        }
        return { value: undefined, done: true };
      }
    };
  }
}

const range = new Range(1, 5);
console.log([...range]);

for (const num of range) {
  console.log(num);
}

Output:

[ 1, 2, 3, 4, 5 ]
1
2
3
4
5

By defining a method under the well-known key Symbol.iterator, the Range class becomes iterable — the spread operator (...) and the for...of loop both automatically know how to walk through it. This is exactly how built-in arrays, strings, Map, and Set support iteration under the hood.

Example 4: The global symbol registry with Symbol.for

const globalSym1 = Symbol.for('app.config');
const globalSym2 = Symbol.for('app.config');

console.log(globalSym1 === globalSym2);
console.log(Symbol.keyFor(globalSym1));

const localSym = Symbol('app.config');
console.log(Symbol.keyFor(localSym));

Output:

true
app.config
undefined

Unlike plain Symbol() calls, Symbol.for() checks a shared, program-wide registry keyed by string. The first call creates and registers the symbol; every later call with the same key retrieves that exact same symbol. A locally created symbol with a matching description is a different value and is not found in the registry, so Symbol.keyFor() returns undefined for it.

Under the Hood

When the JavaScript engine evaluates Symbol('id'), it allocates a new, opaque primitive value with no observable internal structure — unlike objects, it cannot be inspected, cloned field-by-field, or reconstructed from parts. Internally, engines typically track symbols by identity (memory address or an internal unique token), which is why comparison is just an identity check and always fast, O(1).

When a symbol is used as a property key (obj[sym] = value), the engine stores it in a separate internal slot from string-keyed properties. This is why iteration mechanisms that were designed before symbols existed — for...in, Object.keys(), JSON.stringify() — simply never look at that slot; they weren't retrofitted to include it, by design, to avoid breaking existing code and to keep symbol-keyed data out of casual enumeration. Meanwhile, newer reflection APIs like Object.getOwnPropertySymbols() and Reflect.ownKeys() were built to see both kinds of keys, because tooling and library authors sometimes need full introspection.

Well-known symbols (Symbol.iterator, Symbol.toPrimitive, Symbol.toStringTag, Symbol.hasInstance, and others) are pre-created, engine-level singleton symbols exposed as static properties on the global Symbol function. When you write for (const x of myObject), the engine looks up myObject[Symbol.iterator], calls it, and repeatedly calls .next() on the returned iterator object until done is true. This is a purely convention-based protocol — there's no special iterable "type"; anything with a correctly shaped Symbol.iterator method qualifies.

Common Mistakes

Mistake 1: Calling Symbol with new. Since Symbol looks like it should be a constructor, beginners often write new Symbol('id'). This throws a TypeError at runtime because Symbol deliberately has no [[Construct]] behavior.

try {
  const sym = new Symbol('id');
} catch (error) {
  console.log(error instanceof TypeError);
  console.log(error.message);
}

Output:

true
Symbol is not a constructor

Always call Symbol() directly, without new.

Mistake 2: Assuming symbol-keyed properties are truly private. Because symbols are invisible to for...in and Object.keys(), it's tempting to use them to "hide" sensitive data. But any code with a reference to the object can still discover and read every symbol-keyed property using Object.getOwnPropertySymbols() or Reflect.ownKeys().

const secret = Symbol('secret');
const obj = { [secret]: 'hidden value' };

const symbols = Object.getOwnPropertySymbols(obj);
console.log(symbols.length);
console.log(obj[symbols[0]]);

Output:

1
hidden value

Symbols give you collision-avoidance and reduced clutter, not real encapsulation. For genuine privacy, use private class fields (#field) or closures.

Mistake 3: Letting a symbol get implicitly coerced to a string. Writing `Value: ${sym}` throws a TypeError, because JavaScript refuses to implicitly convert symbols to strings (this was a deliberate design choice to avoid silent bugs). You must convert explicitly.

const sym = Symbol('test');
console.log(`Value: ${String(sym)}`);
console.log(`Value: ${sym.toString()}`);
console.log(`Description: ${sym.description}`);

Output:

Value: Symbol(test)
Value: Symbol(test)
Description: test

Best Practices

Use Symbol() for keys that must never collide with any other property, such as metadata added by a library onto objects it doesn't fully own.
Give every symbol a descriptive string argument — it costs nothing and makes debugging (console output, error messages) far easier.
Use Symbol.for() only when you genuinely need the same symbol to be shared across different modules, files, or even realms (like iframes); otherwise prefer plain Symbol() to keep symbols module-local.
Implement Symbol.iterator on custom classes that represent collections or sequences, so they work naturally with for...of, spread syntax, and destructuring.
Don't rely on symbols for security or access control — use private class fields (#name) or module-scoped closures instead.
Remember to use Object.getOwnPropertySymbols() or Reflect.ownKeys() when you need to fully inspect or deep-clone an object that may carry symbol-keyed properties.
Never coerce a symbol implicitly (template literals, + concatenation); always call String(sym) or sym.toString().

Practice Exercises

Exercise 1: Create two symbols, Symbol('color') and Symbol('color'). Log whether they are equal, and log each one's .description. Explain in a comment why the result makes sense.
Exercise 2: Build an object representing a book with a normal title string property and a symbol-keyed property called Symbol('internalId') holding a numeric ID. Verify with JSON.stringify() that the internal ID is not serialized, then retrieve it anyway using Object.getOwnPropertySymbols().
Exercise 3: Write a class Countdown that takes a starting number and implements Symbol.iterator so that spreading an instance (e.g. new Countdown(3)) produces [3, 2, 1]. Test it with both the spread operator and a for...of loop.

Summary

Symbols are a primitive type whose values are always guaranteed to be unique, even when created with identical descriptions.
Create symbols with Symbol('description') — never with new, which throws a TypeError.
Use Symbol.for(key) / Symbol.keyFor(sym) to share a single symbol across your whole program via the global registry.
Symbol-keyed properties are skipped by for...in, Object.keys(), Object.values(), Object.entries(), and JSON.stringify(), but are still discoverable via Object.getOwnPropertySymbols() or Reflect.ownKeys() — so they are not a privacy mechanism.
Well-known symbols like Symbol.iterator, Symbol.toPrimitive, and Symbol.hasInstance let your objects hook into core language behavior such as for...of, spread syntax, and type coercion.
Symbols cannot be implicitly converted to strings; use String(sym), sym.toString(), or sym.description instead.

JavaScript Symbols

Overview / How Symbols Work

Syntax

Examples

Example 1: Basic creation and uniqueness

Example 2: Using a symbol as a collision-proof object key

Example 3: Making a custom object iterable with Symbol.iterator

Example 4: The global symbol registry with Symbol.for

Under the Hood

Common Mistakes

Best Practices

Practice Exercises

Summary

Table of Contents