JavaScript Symbol

Beginner
8 min read
Updated: Nov 2026
3 examples
Primitive type

Definition and Usage

A Symbol is a JavaScript value that is always unique. You create one by calling Symbol(), and no other symbol is ever equal to it, not even one made with the same description. Symbols are mostly used as property keys that cannot clash with any other key.

Symbol is a primitive type, like strings and numbers, so typeof Symbol() is "symbol". You never use new with it. JavaScript also keeps a shared list of symbols, the global symbol registry, which you reach with Symbol.for() and Symbol.keyFor().

This page explains the idea. The Symbol Methods index links the full guides for Symbol.for(), Symbol.keyFor(), toString(), valueOf() and [Symbol.toPrimitive]().

A description is only a label.

The text in Symbol("id") helps you read logs. It does not make the symbol equal to anything else, so Symbol("id") === Symbol("id") is false.

JavaScript Syntax

Create a symbol, use it as a property key, and get a shared symbol from the registry:

JavaScript
const id = Symbol("id");              // a new unique symbol
const user = { name: "Ana" };

user[id] = 101;                       // use it as a property key
console.log(user[id]);                // 101
console.log(typeof id);               // "symbol"

const shared = Symbol.for("app.id");  // the same symbol for the same key
console.log(Symbol.keyFor(shared));   // "app.id"

Core Ideas

Ideas every Symbol tutorial in this series builds on:

IdeaExampleRemember
Symbol()const id = Symbol("id")Creates a new unique symbol every time it is called
Descriptionid.descriptionThe optional label; it does not make symbols equal
Symbol keyobj[id] = 101A property that normal loops and JSON skip
Global registrySymbol.for("app.id")A shared list: the same key gives the same symbol
Symbol.keyFor()Symbol.keyFor(sym)Gives the registry key, or undefined for other symbols
Well-known symbolsSymbol.iteratorBuilt-in symbols that let objects join language features
ConversionString(id)Symbols never turn into text or numbers by themselves

Symbol vs a String Key

A symbol can be used wherever a string key is used. These four kinds of keys behave differently:

KeyHow you get itSame every time?
"id" (string)Write the textYes: the same text is the same key
Symbol("id")Call Symbol()No: a new symbol on every call
Symbol.for("id")Call Symbol.for()Yes: shared through the global registry
Symbol.iteratorBuilt inYes: one symbol for all code

Use a string when everyone should be able to find the key by name. Use Symbol() when the key must belong to your code only. Example 2 shows how symbol keys stay hidden.

How Symbols Work

A symbol is a primitive

Symbols are copied by value like numbers and strings, and typeof says "symbol". They are not objects, which is why new Symbol() throws a TypeError.

Every call makes a new one

Symbol("id") never returns an old symbol. Two symbols with the same description are different values, so they can never overwrite each other as property keys.

Loops and JSON skip symbol keys

Object.keys(), for...in and JSON.stringify() ignore properties whose key is a symbol. To list them, use Object.getOwnPropertySymbols().

No automatic conversion

A symbol never becomes text or a number by itself. "x" + symbol and +symbol throw a TypeError. Convert on purpose with String(symbol) or symbol.description.

The registry shares symbols

Symbol.for(key) looks the key up in one list that all your code shares. The first call creates the symbol, and every later call with the same key returns it.

Real-Life Uses

You will meet symbols in a few special places:

UseHow a symbol helps
Hidden metadataAttach an ID or a flag to an object without showing up in Object.keys() or in JSON.
Constants that never clashUse Symbol("red") as an enum-like value, so no other value can ever be equal to it by accident.
Avoiding key clashesA library can add its own property to your object without overwriting a property that you already have.
Built-in protocolsWell-known symbols such as Symbol.iterator let your own objects work with for...of and the spread syntax.

JavaScript Examples

Three short programs. Each one prints plain text that is the same every time you run it.

Example 1 — Create Symbols and Compare Them

Create symbols with and without the registry, compare them, and break the new rule on purpose.

JavaScript
const a = Symbol("id");
const b = Symbol("id");
const shared1 = Symbol.for("id");
const shared2 = Symbol.for("id");

console.log("typeof: " + typeof a);
console.log("Same description: " + (a.description === b.description));
console.log("a === b: " + (a === b));
console.log("shared1 === shared2: " + (shared1 === shared2));

try {
  new Symbol("id");
} catch (err) {
  console.log("With new: " + err.name);
}

How It Works

  1. A primitive type. typeof a is "symbol". The two symbols a and b have the same description "id".
  2. Still different. a === b is false, because every Symbol() call makes a new value. The description is just a label.
  3. Shared symbols are equal. Both Symbol.for("id") calls return the same symbol from the registry. Using new with Symbol throws a TypeError.

Example 2 — Use a Symbol as a Hidden Key

Add a symbol property to an object and see which tools can and cannot find it.

JavaScript
const ID = Symbol("id");
const user = { name: "Ana", age: 30 };
user[ID] = 101;

const seen = [];
for (const key in user) {
  seen.push(key);
}

console.log("Object.keys: " + Object.keys(user).join(", "));
console.log("JSON: " + JSON.stringify(user));
console.log("for...in: " + seen.join(", "));
console.log("Read by symbol: " + user[ID]);
console.log("Symbol keys: " + Object.getOwnPropertySymbols(user).length);

How It Works

  1. Add a symbol property. user[ID] = 101 works like any other key, but the key is the symbol ID.
  2. Tools skip it. Object.keys(), JSON.stringify() and for...in only see name and age, so the symbol key does not leak into saved data.
  3. You can still reach it. user[ID] returns 101 for code that has the symbol, and Object.getOwnPropertySymbols() counts 1 symbol key.

Example 3 — Make an Object Work with for...of

The built-in symbol Symbol.iterator is the key that for...of and the spread syntax look for. A Countdown class defines it.

JavaScript
class Countdown {
  constructor(start) {
    this.start = start;
  }

  [Symbol.iterator]() {
    let n = this.start;
    return {
      next: () => (n > 0 ? { value: n--, done: false } : { value: undefined, done: true })
    };
  }
}

const countdown = new Countdown(3);
const seen = [];
for (const n of countdown) {
  seen.push(n);
}

console.log("Spread: " + [...countdown].join(", "));
console.log("for...of: " + seen.join(" "));
console.log("keyFor of Symbol.iterator: " + Symbol.keyFor(Symbol.iterator));
console.log("Description: " + Symbol.iterator.description);

How It Works

  1. Define the key. A method named [Symbol.iterator]() tells JavaScript how to walk through the object. It returns an object with a next() function that counts down from start.
  2. The language uses it. for...of and [...countdown] both call that method, so the same object can be looped and spread, giving 3, 2, 1.
  3. Built-in, not registered. Symbol.iterator has a description, but Symbol.keyFor() returns undefined, because well-known symbols are not in the global registry.

Symbol Methods

The Symbol object has two static methods, and every symbol has three instance methods. Each one has its own tutorial:

MethodWhat it does
Symbol.for()Get the shared symbol for a key from the global registry.
Symbol.keyFor()Find the registry key of a shared symbol, or undefined.
toString()Turn a symbol into text such as "Symbol(id)".
valueOf()Get the primitive symbol from a symbol or a wrapper object.
[Symbol.toPrimitive]()How a symbol becomes a primitive value, and which conversions throw.

Full list: Symbol Methods index.

Frequently Asked Questions

A Symbol is a primitive value that is always unique. You create one with Symbol("description"), and it is never equal to any other symbol. Symbols are mostly used as property keys that cannot clash with other keys.
Because each call to Symbol() creates a brand new symbol. The text only describes the symbol and does not make two symbols equal. If you want the same symbol for the same text, use Symbol.for("id").
Symbols are primitive values and not objects, so new Symbol() throws a TypeError. Call Symbol("description") as a normal function. If you really need a wrapper object, use Object(symbol).
No. They are hidden from Object.keys(), for...in and JSON.stringify(), but Object.getOwnPropertySymbols() lists them, so anyone can find them. Use symbols to avoid clashes and accidents. For real privacy use a private field such as #secret in a class.
Use a symbol when a key or constant must not clash with any other value, such as hidden metadata, enum-like constants, or protocol keys like Symbol.iterator. For ordinary data, a plain string key is simpler and easier to read in JSON.

Ready for the method guides?

Open the Symbol Methods index to learn each method with syntax, runnable examples and FAQs.

Symbol Methods index →

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.

14 people found this page helpful