Symbol.for()
Returns the shared symbol registered under a string key, creating it on first use.
Symbol.for(key)- Added in JavaScript ES2015
Parameters
| Parameter | Type | Description |
|---|---|---|
$key | string | The registry key. It is also used as the returned symbol's description. |
Return value
symbolThe existing symbol registered under key, or a newly created and registered symbol if none exists.
Symbol.for() looks a key up in the global symbol registry and returns the symbol stored there, registering a new one only if the key is unseen. Unlike Symbol(), it is idempotent: Symbol.for("x") === Symbol.for("x") is always true.
When to reach for it
Reach for it when two pieces of code that cannot share a variable still need to agree on the same symbol — two bundled copies of a library, a plugin and its host, or code running across realms such as an iframe or a worker. The registry is per-agent and spans realms, so both sides get the identical symbol from the same string.
What trips people up
The registry is a single flat global namespace with no scoping, so short keys like "id" will eventually collide with someone else's. Namespace your keys — Symbol.for("myapp.session") — the way MDN's own examples do. Registered symbols also live for the lifetime of the agent; there is no way to unregister one. Finally, well-known symbols such as Symbol.iterator are not in this registry, so Symbol.for("Symbol.iterator") creates an unrelated symbol.
Example
When to use it
- Let two bundled copies of the same library recognise each other's objects
- Share a protocol key between a page and code running in an iframe or worker
- Define a well-known extension point that plugins can implement without importing your module
Frequently asked questions
What is the difference between Symbol() and Symbol.for()?
Symbol() returns a brand-new symbol every call, while Symbol.for() returns the same symbol for the same string key from a global registry. Use Symbol.for() when separate pieces of code must agree on one key.
Does Symbol.for() work across iframes and workers?
Yes, the global symbol registry is shared across all realms in the same agent, so Symbol.for('k') in an iframe returns the same symbol as in the parent document. Plain Symbol() values are not shared.
Can I remove a symbol from the global registry?
No, there is no unregister operation; entries persist for the lifetime of the agent. Namespace your keys to avoid collisions rather than trying to clean up.
More examples
A cross-copy brand check
isResult() re-derives the symbol from its key rather than closing over BRAND, so a second copy of this module loaded separately would still recognise the same objects.
const BRAND = Symbol.for("myapp.Result");
function makeResult(value) {
return { [BRAND]: true, value };
}
function isResult(x) {
return Boolean(x) && x[Symbol.for("myapp.Result")] === true;
}
console.log(isResult(makeResult(1)));
console.log(isResult({ value: 1 }));
console.log(isResult(null));Registered vs. unregistered symbols
Both symbols carry the description "colour" but only the registered one has a registry key. The last line shows that well-known symbols are not stored in the registry.
const registered = Symbol.for("colour");
const local = Symbol("colour");
console.log(registered === local);
console.log(registered.description === local.description);
console.log(Symbol.keyFor(registered));
console.log(Symbol.keyFor(local));
console.log(Symbol.for("Symbol.iterator") === Symbol.iterator);
Discussion