JavaScript Symbol.for() Method

Beginner
6 min read
Updated: Nov 2026
3 examples
Static method

Definition

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
CallWhat 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.

A standard JavaScript static method (ES2015) of the Symbol object: call it as Symbol.for(), not on a symbol you already have. No import required. Siblings: Symbol.keyFor(), toString(), valueOf(), [Symbol.toPrimitive]().

Library declarations
JavaScript
// ECMAScript 2015 (ES6)
Symbol.for(key)

// key   : converted to a string
// returns: a symbol
// throws : TypeError if key is a symbol

Parameters

ParameterDescription
keyThe 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 ValueDescription
symbolThe 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);
Try It Yourself

How It Works

  1. 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.
  2. Compare them. first === second is true, because both variables hold one and the same symbol.
  3. 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);
Try It Yourself

How It Works

  1. 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".
  2. A local symbol does not match. localKey has the same description but is a different symbol, so account[localKey] finds nothing and gives undefined.
  3. 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);
}
Try It Yourself

How It Works

  1. 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.
  2. A symbol cannot be a key. JavaScript cannot turn a symbol into a string by itself, so Symbol.for(Symbol("x")) throws a TypeError.
  3. No new. Symbol.for is a normal function, not a constructor, so new Symbol.for("x") throws a TypeError as well.

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.

ES2015 Standard since
Google Chrome 40+ · Desktop & Mobile
Full support
Microsoft Edge 12+ · Chromium and legacy
Full support
Mozilla Firefox 36+ · Desktop & Mobile
Full support
Apple Safari 9+ · macOS & iOS
Full support
Opera 27+ · Chromium based
Full support
Samsung Internet Recent versions · Android
Supported
Android WebView 40+ · Chromium based
Supported
Node.js 0.12+ · Server runtime
Supported
Deno Supported · JavaScript runtime
Supported
Bun Supported · JavaScript runtime
Supported
Internet Explorer No 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.

Next: Symbol.keyFor()

Learn how to go the other way: give a symbol, and get back the key it was registered with.

Symbol.keyFor() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

12 people found this page helpful