Symbols

Symbols are one-of-a-kind property keys

A symbol is a value that is always unique. No other value is ever equal to it. A symbol is a primitive value, like a number or a string.

The main job of a symbol is to be a property key. A property key is the name you use to store and read a value on an object, like name in user.name. Because every symbol is unique, a symbol key can never be the same as someone else's key by accident.

You met symbol in the Data types lesson: typeof Symbol("id") is "symbol". In Object basics, you saw computed property names, like { [key]: value }. The square brackets mean "use the value of key as the property name". A symbol can go inside those brackets. That is how a symbol becomes a property key.

Here is a first example. A variable keeps the symbol. Square brackets use that exact symbol to write and read a property.

const userKey = Symbol("userId");
const user = { name: "Asha" };
user[userKey] = 42;
console.log(user[userKey]);
console.log(user.userId);

• Line 1 makes a symbol and saves it in userKey. The text "userId" is the symbol's description: a label for people to read.
• Line 2 makes a user object with one string key, name.
• Line 3 stores 42 on user, with the symbol as the key.
• Line 4 reads with the same symbol, so it prints 42.
• Line 5 prints undefined. user.userId looks for a key that is the text "userId". That text is not the symbol, even though the symbol's description says userId.

This lesson covers:

• Symbol() and descriptions.
• How to turn a symbol into text.
• The shared list of symbols, called the registry, with Symbol.for.
• Symbol keys that ordinary object lists skip.
• A first look at built-in symbols like Symbol.iterator.

Call Symbol() to make a new symbol. You can put a description inside the brackets, like Symbol("id"). The description is optional. It shows up when you print the symbol, so it helps when you look for bugs. It does not decide whether two symbols are equal.

Pick a description below and step through the code. Lines 1 and 2 use the same text. JavaScript still makes two different symbols.

1const id = Symbol("id");Run2const sameTag = Symbol("id");3console.log(id === sameTag);4console.log(id === id);5console.log(typeof id);6console.log(id.description);7console.log(String(id));

You can leave the description out. Then a log shows less, but the symbol is still unique.

const note = Symbol();
console.log(note.description === undefined);
console.log(String(note));

This prints true, then Symbol(). Line 2 checks that the description is missing, which means it is undefined. Line 3 turns the symbol into text. With no description, the text is just Symbol().

Many values turn into text on their own. For example, "Age: " + 5 gives "Age: 5". Symbols refuse to do this. That is on purpose: it stops you from mixing up a unique key with ordinary text by mistake.

To get text from a symbol, ask for it directly. There are two ways:

• String(id)
• id.toString()

Joining a symbol to text with + throws a TypeError. A TypeError is the error JavaScript throws when a value is the wrong type for what you asked.

1const id = Symbol("id");Run2console.log(String(id));3console.log(id.toString());4console.log("Key: " + id);

Sometimes two separate files really do need the same symbol. For that, JavaScript keeps one shared list of symbols, called the global symbol registry. Each symbol in it is saved under a text key, such as "app.id".

Call Symbol.for("app.id"), and you get the symbol saved under that key. If there isn't one yet, JavaScript makes it and saves it. Everyone who uses that exact key gets the same symbol.

Step through the code below. Line 1 makes a local symbol: a symbol from Symbol(), which is not in the registry. Lines 2 and 3 ask the registry. Symbol.keyFor, on lines 6 and 7, does the opposite lookup. Give it a registry symbol, and it returns the key that symbol is saved under.

1const local = Symbol("app.id");Run2const sharedA = Symbol.for("app.id");3const sharedB = Symbol.for("app.id");4console.log(local === Symbol("app.id"));5console.log(sharedA === sharedB);6console.log(Symbol.keyFor(sharedA));7console.log(Symbol.keyFor(local));

Registry keys are always text. If you pass something else, JavaScript turns it into text first. So the number 7 and the string "7" find the same registry entry. In real code, write clear text keys, so the next reader doesn't need to know this rule.

const first = Symbol.for(7);
const second = Symbol.for("7");
console.log(first === second);
console.log(Symbol.keyFor(first));

The output is true, then 7. Line 1 asks for the key 7, which becomes the text "7". Line 2 asks for "7", so both lines get one shared symbol. Line 4 prints the key that symbol is saved under.

The table compares the two ways to make a symbol. Read each row as a question, then the answer for each way.

Most property keys are strings. A property whose key is a symbol is called a symbol-keyed property. Many everyday tools skip symbol-keyed properties:

• Object.keys(obj) returns an array of the object's string keys.
• A for...in loop visits the object's string keys one by one.
• JSON.stringify(obj) turns the object into JSON text, so you can save or send it.

That makes symbol keys useful for metadata: extra notes about an object that are not part of its main data. Press each tool below and see what it finds.

1const metadata = Symbol("metadata");2const user = { name: "Ada" };3user[metadata] = { role: "admin" };4 5Object.keys(user);6// ["name"]7 8JSON.stringify(user);9// "{\"name\":\"Ada\"}"10 11Object.getOwnPropertySymbols(user);12// [Symbol(metadata)]13 14Reflect.ownKeys(user);15// ["name", Symbol(metadata)]16 17user[metadata];18// { role: "admin" }

["name"]

A symbol key can sit next to a string key with the same name. Neither one overwrites the other.

const processed = Symbol("processed");
const record = { processed: "from app" };
record[processed] = true;
console.log(record.processed);
console.log(record[processed]);

It prints from app, then true. Line 4 uses a dot, so it reads the string key "processed". Line 5 uses square brackets with the saved symbol, so it reads the symbol key. They are two separate properties.

Each property also has a setting called enumerable. When it is true, the property is meant to show up when you list an object's properties. A property you add with = is enumerable. Object.getOwnPropertyDescriptor(obj, key) returns an object that describes one property, including this setting.

const metadata = Symbol("metadata");
const user = {};
user[metadata] = "local";
console.log(Object.getOwnPropertyDescriptor(user, metadata).enumerable);
console.log(Object.keys(user).length);

The output is true, then 0. Line 4 shows that the symbol property is enumerable. Line 5 shows that Object.keys still finds no keys. It only returns string keys, so the symbol key is left out.

The table lists the tools you can use on an object. "Own" keys are keys stored on the object itself. "Inherited" keys come from another object it is linked to. Read each row as: does this tool show symbol keys, and what does it list?

The property is not locked away. Three tools still reach it:

• Object.getOwnPropertySymbols(obj) returns an array of the object's symbol keys.
• Reflect.ownKeys(obj) returns string keys and symbol keys together.
• obj[symbolKey] reads the property directly, if you have the symbol.

JavaScript also comes with built-in symbols, called well-known symbols. You find them on Symbol, like Symbol.iterator. JavaScript itself looks for these keys on objects. If an object has a property under one of these keys, JavaScript uses it to change how the object behaves.

You don't need to learn them all today. Just learn to recognize them.

1typeof [][Symbol.iterator];2typeof "hi"[Symbol.iterator];3typeof ({})[Symbol.iterator];4for (const value of {}) {5  console.log(value);6}7Object.prototype.toString.call([]);8const tagged = {9  [Symbol.toStringTag]: "LibraryCard",10};11Object.prototype.toString.call(tagged);

typeof [][Symbol.iterator] → function

• Symbol.iterator: a for...of loop looks for a function under this key. Arrays and strings have one, so for...of works on them. Plain objects don't have one.
• Symbol.toStringTag: sets the name inside labels like [object Array]. These labels come from Object.prototype.toString.
• Symbol.toPrimitive: decides how an object turns into a primitive value, like a number or a string. The next lesson covers it, so this is only a first look.

Where you’ll use symbols

The most common use is adding metadata to objects you don't own. Imagine a small library: code written by someone else that your app uses. The library receives user objects from your app. Your app might already use keys like id, status, or source. If the library adds its own notes under a symbol key, it can never overwrite one of your app's keys.

const processed = Symbol("processed");

export function markProcessed(record) {
  record[processed] = true;
  return record;
}

export function wasProcessed(record) {
  return record[processed] === true;
}

The library keeps the symbol inside its own file. Only its two functions use it:

• markProcessed(record) stores true under the symbol key.
• wasProcessed(record) checks whether that true is there.

Your app calls wasProcessed. It never needs to know the key. The app's own data looks the same as before, because the symbol key doesn't show up in Object.keys or in JSON.

const processed = Symbol("processed");
const record = { id: 3 };
record[processed] = true;
console.log(record.id);
console.log(record[processed]);

It prints 3, then true. Line 4 reads the app's id. Line 5 reads the library's note.

Keep important data, like an ID, on string keys. Then it stays in the JSON when you save or send the object. Use symbol keys for notes that only your own code needs.

Remember: symbol keys are not secret. They stop accidental name clashes, and they stay out of JSON. But tools like Reflect.ownKeys can still find them.

Common misconceptions

Key takeaways

• Symbol() makes a new, unique primitive value every time.
• The description is a label for people. It does not make two symbols equal.
• Symbol.for and Symbol.keyFor use a shared registry, for symbols you share on purpose.
• Object.keys, for...in, and JSON.stringify skip symbol-keyed properties. Object.getOwnPropertySymbols and Reflect.ownKeys can still find them.
• Well-known symbols, such as Symbol.iterator, are keys JavaScript looks for to change how an object behaves.

Up next: Object to primitive conversion. It explains Symbol.toPrimitive in full.