Symbol.keyFor(sym) answers one question: "which key was this symbol registered with?" If the symbol came from Symbol.for(key), you get that key back as a string.
If the symbol is not in the global symbol registry, the result is undefined. That is the case for a symbol made with Symbol() and for the built-in symbols such as Symbol.iterator. This makes keyFor() a simple way to check whether a symbol is shared or local.
Remember
Symbol.keyFor(sym)
sym → must be a symbol
returns → the key (a string)
or undefined
Made with Symbol.for() → the key
Made with Symbol() → undefined
Symbol.iterator & co. → undefined
Syntax
Call it on the Symbol object and pass a symbol. Compare the result with undefined.
// ECMAScript 2015 (ES6)
Symbol.keyFor(sym)
// sym : a symbol
// returns: a string or undefined
// throws : TypeError if sym is not a symbol
Parameters
Parameter
Description
sym
Required. The symbol to look up. It must be a symbol. Any other value, even a string that looks like a key, throws a TypeError.
Return Value
Return Value
Description
string
The key of a shared symbol, exactly as it was used with Symbol.for() (after conversion to a string). The key can be an empty string.
undefined
The symbol is not in the global registry: it was made with Symbol(), or it is a built-in symbol such as Symbol.iterator.
TypeError (thrown)
The argument is not a symbol, or no argument was passed.
JavaScript Examples
Example 1 — Find the Key of a Symbol
Look up the key of a shared symbol, a local symbol, and a built-in symbol.
JavaScript
const shared = Symbol.for("app.theme");
const local = Symbol("app.theme");
console.log("Key of shared symbol: " + Symbol.keyFor(shared));
console.log("Key of local symbol: " + Symbol.keyFor(local));
console.log("Key of Symbol.iterator: " + Symbol.keyFor(Symbol.iterator));
console.log("Description of local symbol: " + local.description);
Key of shared symbol: app.theme
Key of local symbol: undefined
Key of Symbol.iterator: undefined
Description of local symbol: app.theme
How It Works
A shared symbol has a key.shared came from Symbol.for("app.theme"), so keyFor() returns "app.theme".
Local and built-in symbols have none.local was made with Symbol() and Symbol.iterator is built in. Neither is in the registry, so both give undefined.
Description is different. The local symbol still has a description, "app.theme", but a description is only a label. It does not put the symbol in the registry.
Example 2 — Check If a Symbol Is Shared or Local
A small function that reports what kind of symbol it received. It compares with undefined, so an empty key still works.
JavaScript
function describe(sym) {
const key = Symbol.keyFor(sym);
if (key === undefined) {
return "local symbol";
}
return "shared symbol with key [" + key + "]";
}
console.log(describe(Symbol.for("app.user")));
console.log(describe(Symbol("app.user")));
console.log(describe(Symbol.iterator));
console.log(describe(Symbol.for("")));
shared symbol with key [app.user]
local symbol
local symbol
shared symbol with key []
How It Works
Ask for the key. The function stores the result of Symbol.keyFor(sym) and decides what to say.
Shared or local.Symbol.for("app.user") has a key. Symbol("app.user") and Symbol.iterator do not, so both are reported as local.
Empty keys still count.Symbol.for("") has the key "", which is falsy. Because the check is key === undefined, it is correctly reported as shared. The brackets in the output show that the key is empty.
Example 3 — See Which Arguments Throw an Error
Pass a string, a number, nothing, and a real symbol. The catch block prints the error type only, because the message text differs between browsers.
a string -> TypeError
a number -> TypeError
nothing -> TypeError
a symbol -> ok
How It Works
Four small tests. Each test is a function in an array, so one loop can run them all and catch errors the same way.
Only symbols are allowed. A string, a number, and a missing argument are not symbols, so keyFor() throws a TypeError for each of them. It does not try to convert them.
A real symbol works.Symbol.for("ok") is a symbol, so the call returns its key, "ok", and the loop prints it.
Compatibility
Browser & Runtime Support
Symbol.keyFor() is part of ES2015 (ES6). Every current browser and Node.js has it.
✓ ES2015 · Widely supported
Symbol.keyFor()
Supported in Chrome 40+, Edge 12+, Firefox 36+, Safari 9+, Opera 27+ and Node.js 0.12+. Internet Explorer never got it.
ES2015Standard since
Google Chrome40+ · Desktop & Mobile
Full support
Microsoft Edge12+ · Chromium and legacy
Full support
Mozilla Firefox36+ · Desktop & Mobile
Full support
Apple Safari9+ · macOS & iOS
Full support
Opera27+ · Chromium based
Full support
Samsung InternetRecent versions · Android
Supported
Android WebView40+ · Chromium based
Supported
Node.js0.12+ · Server runtime
Supported
DenoSupported · JavaScript runtime
Supported
BunSupported · JavaScript runtime
Supported
Internet ExplorerNo native support
Not supported
Symbol.keyFor()Excellent
Bottom line: Safe to use in every current browser and in Node.js. The only thing to plan for is Internet Explorer, which has no Symbol at all.
Frequently Asked Questions
It returns the key that a shared symbol was registered with. If you made the symbol with Symbol.for("app.theme"), then Symbol.keyFor(symbol) returns "app.theme". For any other symbol it returns undefined.
Because the symbol was not made with Symbol.for(). Symbols made with Symbol() are local and are never put in the global registry. Built-in symbols such as Symbol.iterator are not registered either.
The description is a text label that any symbol can have, shared or not. The key exists only for shared symbols made with Symbol.for(). A local symbol can have a description, but keyFor() still returns undefined for it.
Use Symbol.keyFor(sym) !== undefined. Compare with undefined and not with a truthy test, because an empty string is a valid key and it is falsy.
No. The argument must be a symbol. A string, a number or a missing argument throws a TypeError. To get a symbol from a string key, use Symbol.for(key) instead.