Symbols

Symbols are one-of-a-kind property keys

A symbol is a primitive value made to be unique. You mostly use symbols as object property keys when you want a key that cannot accidentally collide with somebody else’s key.

You met symbol in the Data types lesson: typeof Symbol("id") is "symbol". In Object basics, you also saw computed property names: { [key]: value }. Put those ideas together and a symbol can become a special object key.

This lesson covers Symbol(), descriptions, the shared registry, symbol-keyed properties that ordinary object lists skip, and a first peek at well-known symbols like Symbol.iterator.

Call Symbol(description) to create a symbol. The description is optional. It is useful in debugging output, but it does not participate in equality.

Change the description below and step through. Even when both calls use the same text, JavaScript creates two different symbols.

1const id = Symbol("id");Run2const sameTag = Symbol("id");3console.log(id === sameTag);4console.log(id === id);5console.log(typeof id);6console.log(id.description);7console.log(String(id));

Symbols intentionally resist implicit string conversion. That sounds fussy until it saves you from accidentally treating a unique key like ordinary text.

The safe conversions are explicit: String(id) or id.toString(). Concatenating with + throws a TypeError in JavaScript engines such as V8.

1const id = Symbol("id");Run2console.log(String(id));3console.log(id.toString());4console.log("Key: " + id);

Sometimes two separate files really do need the same symbol. The global symbol registry is a shared key cabinet. Ask for Symbol.for("app.id"), and everyone using that exact key gets the same symbol back.

1const local = Symbol("app.id");Run2const sharedA = Symbol.for("app.id");3const sharedB = Symbol.for("app.id");4console.log(local === Symbol("app.id"));5console.log(sharedA === sharedB);6console.log(Symbol.keyFor(sharedA));7console.log(Symbol.keyFor(local));

Object property keys are usually strings. Symbols are allowed too, which gives you a useful trick: attach metadata without showing up in everyday inventories such as Object.keys, for...in, or JSON.stringify.

1const metadata = Symbol("metadata");2const user = { name: "Ada" };3user[metadata] = { role: "admin" };4 5Object.keys(user);6// ["name"]7 8JSON.stringify(user);9// "{\"name\":\"Ada\"}"10 11Object.getOwnPropertySymbols(user);12// [Symbol(metadata)]13 14Reflect.ownKeys(user);15// ["name", Symbol(metadata)]16 17user[metadata];18// { role: "admin" }

["name"]

The property is not locked. Object.getOwnPropertySymbols finds symbol keys, Reflect.ownKeys finds string and symbol keys, and direct bracket access works if you have the symbol.

JavaScript also has built-in symbol keys called well-known symbols. They are hooks where objects can opt into language behavior. You do not need to master them today; just recognize the shape.

1typeof [][Symbol.iterator];2typeof "hi"[Symbol.iterator];3typeof ({})[Symbol.iterator];4for (const value of {}) {5  console.log(value);6}7Object.prototype.toString.call([]);8const tagged = {9  [Symbol.toStringTag]: "LibraryCard",10};11Object.prototype.toString.call(tagged);

typeof [][Symbol.iterator] → function

• Symbol.iterator is why for...of works on arrays and strings. Plain objects do not have it by default.
• Symbol.toStringTag customizes labels such as [object Array].
• Symbol.toPrimitive controls object-to-primitive conversion. That is the focus of the next lesson, so this is only a teaser.

Where you’ll use symbols

The everyday use case is metadata on objects you do not own. Imagine a small library that receives user objects from an app. The app might already use keys like id, status, or source. A symbol key avoids collisions.

const processed = Symbol("processed");

export function markProcessed(record) {
  record[processed] = true;
  return record;
}

export function wasProcessed(record) {
  return record[processed] === true;
}

The important trade-off: symbol metadata is polite, not secret. It avoids accidental name clashes and stays out of JSON, but inspection tools can still reveal it.

Common misconceptions

Key takeaways

• Symbol() creates a unique primitive value every time.
• The description helps humans read logs; it does not make symbols equal.
• Symbol.for and Symbol.keyFor work with a shared registry for intentionally shared keys.
• Symbol-keyed object properties are skipped by Object.keys, for...in, and JSON.stringify, but symbol-aware tools can find them.
• Well-known symbols such as Symbol.iterator are hooks JavaScript checks for special behavior.

Up next: Object to primitive conversion — including the deeper version of Symbol.toPrimitive teased here.