Symbol.for(key) gives you a shared symbol. JavaScript keeps a list of shared symbols called the global symbol registry. When you call Symbol.for("app.theme"), JavaScript looks for the key "app.theme" in that list. If it is there, you get that exact symbol back. If not, JavaScript creates a new symbol, stores it under that key, and returns it.
This is different from Symbol("app.theme"), which makes a brand new symbol every time. With Symbol.for(), two different files, functions or libraries that use the same key end up with the same symbol, so they can agree on a property name without passing the symbol around.
Remember
Symbol.for(key)
key → converted to a string first
returns → the shared symbol for that key
First call with a key → creates and stores a symbol
Every later call → returns the same symbol
Never write: new Symbol.for(key)
Syntax
Call it on the Symbol object and pass a key. Use the same key anywhere to get the same symbol.
JavaScript
const shared = Symbol.for("app.theme");
const again = Symbol.for("app.theme");
console.log(shared === again); // true
console.log(shared === Symbol("app.theme")); // false: Symbol() is always new
Call
What it does
Symbol.for("app.theme")
Return the shared symbol for the key "app.theme", creating it the first time.
Symbol.for(42)
The key is converted to a string, so this is the same as Symbol.for("42").
Symbol.for()
No key means the key "undefined". Always pass a key to avoid surprises.
Symbol.keyFor(sym)
The opposite direction: give a symbol, get its registry key back.
// ECMAScript 2015 (ES6)
Symbol.for(key)
// key : converted to a string
// returns: a symbol
// throws : TypeError if key is a symbol
Parameters
Parameter
Description
key
The text that identifies the shared symbol. JavaScript converts it to a string, so 42 and "42" give the same symbol, and a missing key becomes the text "undefined". The key also becomes the description of a newly created symbol. A symbol cannot be turned into a string, so passing one as the key throws a TypeError.
Return Value
Return Value
Description
symbol
The shared symbol for the key. You get the very same symbol every time you pass the same key. Its description is the key.
TypeError (thrown)
The key is a symbol, or Symbol.for was called with new. It is a plain function, not a constructor.
JavaScript Examples
Example 1 — Get the Same Symbol Twice
Ask for the same key two times, and compare the result with a symbol made by Symbol().
JavaScript
const first = Symbol.for("app.theme");
const second = Symbol.for("app.theme");
const local = Symbol("app.theme");
console.log("Same key gives the same symbol: " + (first === second));
console.log("Symbol() is always new: " + (first === local));
console.log("Text of the symbol: " + first.toString());
console.log("Description: " + first.description);
Same key gives the same symbol: true
Symbol() is always new: false
Text of the symbol: Symbol(app.theme)
Description: app.theme
How It Works
Look up or create. The first Symbol.for("app.theme") finds no such key, so it creates a symbol and stores it in the registry. The second call finds the key and returns the same symbol.
Compare them.first === second is true, because both variables hold one and the same symbol.
Symbol() is not shared.local was made with Symbol(), which never uses the registry, so it is a different symbol even with the same description. The last two lines show that the key becomes the description.
Example 2 — Share a Property Key Between Two Functions
Two functions use Symbol.for() with the same key, so they read and write the same hidden property.
JavaScript
function setRole(user, role) {
user[Symbol.for("app.role")] = role;
}
function getRole(user) {
return user[Symbol.for("app.role")];
}
const localKey = Symbol("app.role");
const account = {};
setRole(account, "admin");
console.log("Role read back: " + getRole(account));
console.log("Read with a local symbol: " + account[localKey]);
console.log("Normal keys: " + Object.keys(account).length);
console.log("Symbol keys: " + Object.getOwnPropertySymbols(account).length);
Role read back: admin
Read with a local symbol: undefined
Normal keys: 0
Symbol keys: 1
How It Works
One key, one symbol. Both setRole() and getRole() call Symbol.for("app.role"), so they use the same symbol as the property name. The role is saved and read back as "admin".
A local symbol does not match.localKey has the same description but is a different symbol, so account[localKey] finds nothing and gives undefined.
The property stays hidden.Object.keys() skips symbol keys, so it finds 0 normal keys. Object.getOwnPropertySymbols() lists the 1 symbol key.
Example 3 — Check the Rules for the Key
Try numbers, a missing key, an empty key, a symbol as the key, and new. The catch block prints the error type only, because the message text differs between browsers.
JavaScript
console.log("Number 42 and text 42: " + (Symbol.for(42) === Symbol.for("42")));
console.log("No key and text undefined: " + (Symbol.for() === Symbol.for("undefined")));
console.log("Empty key description: [" + Symbol.for("").description + "]");
try {
Symbol.for(Symbol("x"));
} catch (err) {
console.log("Symbol as key: " + err.name);
}
try {
new Symbol.for("x");
} catch (err) {
console.log("With new: " + err.name);
}
Number 42 and text 42: true
No key and text undefined: true
Empty key description: []
Symbol as key: TypeError
With new: TypeError
How It Works
Keys become strings. The number 42 turns into "42", and a missing key turns into "undefined", so each pair gives the same symbol. An empty string is a valid key too, and its description is empty.
A symbol cannot be a key. JavaScript cannot turn a symbol into a string by itself, so Symbol.for(Symbol("x")) throws a TypeError.
No new.Symbol.for is a normal function, not a constructor, so new Symbol.for("x") throws a TypeError as well.
Compatibility
Browser & Runtime Support
Symbol.for() is part of ES2015 (ES6). Every current browser and Node.js has it.
✓ ES2015 · Widely supported
Symbol.for()
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.for()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 a shared symbol for a key. JavaScript keeps a global list of shared symbols. If the key is already in the list, you get that symbol. If not, JavaScript creates a new symbol, stores it under the key, and returns it.
Symbol("id") creates a new unique symbol every time you call it. Symbol.for("id") returns the same symbol every time for the same key, because it uses the global registry. Use Symbol() for private-style keys and Symbol.for() when separate pieces of code must find the same symbol.
No. Symbol.for is a normal function, so new Symbol.for("x") throws a TypeError. The same is true for Symbol itself: new Symbol("x") also throws a TypeError, because symbols are not objects.
Use Symbol.keyFor(symbol). It returns the key as a string for symbols made with Symbol.for(), and undefined for symbols made with Symbol() or for built-in symbols such as Symbol.iterator.
No. Once a key is in the global registry it stays there until the program ends. For that reason, use a small number of fixed keys, such as "myapp.userId", and do not create keys from user input or inside a loop.