Symbol.keyFor()
Returns the global registry key for a symbol, or undefined if it was never registered.
Symbol.keyFor(sym)- Added in JavaScript ES2015
Parameters
| Parameter | Type | Description |
|---|---|---|
$sym | symbol | The symbol to look up in the global symbol registry. |
Return value
string | undefinedThe registry key string if sym was created by Symbol.for(); otherwise undefined.
Errors
Throws a TypeError if sym is not a symbol.
Symbol.keyFor() is the inverse of Symbol.for(): it searches the global symbol registry for the given symbol and returns the string it was registered under. If the symbol is not in the registry it returns undefined.
When to reach for it
Its practical use is a predicate: Symbol.keyFor(sym) !== undefined tells you whether a symbol is shared and therefore reproducible from a string. That matters when you serialise structures with symbol keys, or when you log a symbol and want the canonical key rather than a description someone may have chosen arbitrarily. It is also the only way to recover the key when all you hold is the symbol itself.
What trips people up
Two things return undefined and surprise people: symbols made with plain Symbol(), and every well-known symbol — Symbol.keyFor(Symbol.iterator) is undefined, even though the symbol clearly has a canonical name. Also note that description and the registry key are different concepts: a registered symbol has both and they match, an unregistered one may have a description but never a key. Passing a non-symbol throws a TypeError rather than returning undefined.
Example
When to use it
- Decide whether a symbol key can be safely serialised and rebuilt with Symbol.for()
- Log the canonical registry key of a symbol instead of its free-text description
- Guard an API that only accepts registry-backed symbols as extension points
Frequently asked questions
Why does Symbol.keyFor() return undefined for my symbol?
Because the symbol was not created by Symbol.for(). Plain Symbol() values and well-known symbols such as Symbol.iterator are not in the global registry, so keyFor() reports undefined for them.
What is the difference between Symbol.keyFor() and the description property?
keyFor() returns the global registry key and is undefined for unregistered symbols, while description returns the free-text label passed to Symbol() and never consults the registry. For a Symbol.for() symbol the two strings happen to be equal.
Does Symbol.keyFor() throw?
Yes, it throws a TypeError if the argument is not a symbol primitive — including a string, undefined, or a boxed Symbol wrapper object.
More examples
A "is this symbol shareable?" check
Only the registry-backed symbol passes the check, and the last line confirms the round trip: a key recovered by keyFor() feeds straight back into Symbol.for() to yield the identical symbol.
const isShared = (sym) => Symbol.keyFor(sym) !== undefined;
console.log(isShared(Symbol.for("a")));
console.log(isShared(Symbol("a")));
console.log(isShared(Symbol.toStringTag));
// Round-trip a shared symbol through a string
const key = Symbol.keyFor(Symbol.for("myapp.route"));
console.log(Symbol.for(key) === Symbol.for("myapp.route"));Non-symbol arguments throw
A string argument raises a TypeError rather than returning undefined. The second line shows a wrapper object is also rejected in the same way — keyFor requires a symbol primitive.
try {
Symbol.keyFor("myapp.id");
} catch (err) {
console.log(err.constructor.name);
}
console.log(Symbol.keyFor(Object(Symbol.for("boxed"))));
Discussion