JavaScript Symbol.keyFor() Method

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

Definition

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.

JavaScript
const shared = Symbol.for("app.theme");
const local = Symbol("app.theme");

console.log(Symbol.keyFor(shared));   // "app.theme"
console.log(Symbol.keyFor(local));    // undefined
CallWhat it does
Symbol.keyFor(shared)Return the key that shared was registered with, for example "app.theme".
Symbol.keyFor(Symbol("x"))Return undefined, because a local symbol is not in the registry.
Symbol.keyFor(Symbol.iterator)Return undefined. Built-in symbols are not registered either.
Symbol.keyFor(sym) !== undefinedA short test for "is this symbol shared?".

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

Library declarations
JavaScript
// ECMAScript 2015 (ES6)
Symbol.keyFor(sym)

// sym    : a symbol
// returns: a string or undefined
// throws : TypeError if sym is not a symbol

Parameters

ParameterDescription
symRequired. 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 ValueDescription
stringThe 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.
undefinedThe 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);
Try It Yourself

How It Works

  1. A shared symbol has a key. shared came from Symbol.for("app.theme"), so keyFor() returns "app.theme".
  2. 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.
  3. 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("")));
Try It Yourself

How It Works

  1. Ask for the key. The function stores the result of Symbol.keyFor(sym) and decides what to say.
  2. Shared or local. Symbol.for("app.user") has a key. Symbol("app.user") and Symbol.iterator do not, so both are reported as local.
  3. 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.

JavaScript
const tests = [
  ["a string", () => Symbol.keyFor("app.theme")],
  ["a number", () => Symbol.keyFor(42)],
  ["nothing", () => Symbol.keyFor()],
  ["a symbol", () => Symbol.keyFor(Symbol.for("ok"))]
];

for (const [label, test] of tests) {
  try {
    console.log(label + " -> " + test());
  } catch (err) {
    console.log(label + " -> " + err.name);
  }
}
Try It Yourself

How It Works

  1. Four small tests. Each test is a function in an array, so one loop can run them all and catch errors the same way.
  2. 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.
  3. A real symbol works. Symbol.for("ok") is a symbol, so the call returns its key, "ok", and the loop prints it.

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.

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

Next: toString()

Learn how to turn a symbol into text, which JavaScript refuses to do for you with + or a template literal.

toString() 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.

10 people found this page helpful