Well-known symbols

Built-in keys that JavaScript looks for

A symbol is a special value you can use as a property key. Every symbol is unique, so it never clashes with a normal key like "name". You met symbols in the Symbols lesson.

JavaScript also comes with a few symbols that are already made. They live on Symbol, for example Symbol.iterator. These are called well-known symbols.

Here is why they matter. Some built-in code, like spread [...list] or a for...of loop, looks for a method at one of these keys. If your object has that method, JavaScript calls it for you. In this lesson, a method like that is called a hook.

The table lists every hook in this lesson. Each row is one well-known symbol: the code that calls it, and when to use it.

A hook lets your object work with built-in code, like an array does. Use hooks with care, though. A good hook gives the result a reader expects. A bad hook makes normal-looking code do something surprising.

The loop hooks are the easiest place to start. These four all call Symbol.iterator to get values from an object:

• a for...of loop
• spread, like [...cart]
• destructuring, like const [first] = cart
• Array.from(cart)

Symbol.asyncIterator does the same job for a for await...of loop. That loop waits for each value, because each one may arrive later.

The Iteration protocols lesson shows every detail of how this works. Here, just follow three steps: the loop finds the method at the symbol key, calls it, and takes the values it hands back.

const cart = {
  *[Symbol.iterator]() { yield "tea"; yield "bread"; },
};
console.log([...cart].join(", "));

Line 2 adds a method to cart. The square brackets around Symbol.iterator let you use the symbol as the key. The star * makes the method a generator: a function that hands out values one at a time with yield. This one yields "tea", then "bread".

Line 4 spreads the cart with [...cart]. JavaScript calls the method, collects both values, and prints tea, bread. Without the method, spread throws a TypeError. It doesn't guess how to read the object.

(async () => {
  const pages = { async *[Symbol.asyncIterator]() { yield 1; yield 2; } };
  const values = [];
  for await (const page of pages) values.push(page);
  console.log(values.join(", "));
})();

Line 2 gives pages an async generator at the key Symbol.asyncIterator. It yields the page numbers 1 and 2. Line 4 is a for await...of loop. It waits for each page and pushes it into values. Line 5 prints 1, 2. A normal for...of loop can't use this method; it only looks for Symbol.iterator.

1const gadget = {2  name: "price tag",3  value: 25,4  [Symbol.toPrimitive](hint) { return hint === "string" ? "PriceTag" : 25; },5  [Symbol.toStringTag]: "CatalogPrice",6  [Symbol.iterator]: function* () { yield "label"; yield "value"; },7  async *[Symbol.asyncIterator]() { yield "async label"; yield "async value"; },8  [Symbol.isConcatSpreadable]: true,9};10 11class PriceLike {12  static [Symbol.hasInstance](value) {13    return value?.value === 25;14  }15}

Try this: turn Symbol.iterator off, then press spread. You don't get an empty array. You get an error, because spread needs that method. Then turn Symbol.asyncIterator off and press for await to see the same thing for the async loop.

A primitive is a plain value that is not an object, such as a string, a number, or a boolean. Sometimes JavaScript needs to turn an object into a primitive, for example to put it inside a template literal. The Object to primitive conversion lesson shows all the steps.

The first thing JavaScript tries is a method at the key Symbol.toPrimitive. The method gets one argument, called the hint. The hint is a word that says what kind of value the code wants:

• A template literal, like `${price}`, sends "string".
• Math, like price * 2, sends "number".
• + with an object, and ==, send "default".

1const price = {Run2  cents: 2500,3  [Symbol.toPrimitive](hint) {4    console.log("hint", hint);5    return hint === "string" ? "$25.00" : 25;6  },7};8 9console.log(`${price}`);

const price = {
  [Symbol.toPrimitive](hint) { return hint === "number" ? 25 : "$25"; },
};
console.log(`${price}`);
console.log(price * 2);

Line 2 is the hook. If the hint is "number", it returns 25. For any other hint, it returns the text "$25".

Line 4 is a template literal, so the hint is "string" and it prints $25. Line 5 multiplies, so the hint is "number". The method returns 25, and 25 * 2 prints 50.

The hook must return a primitive. If it returns an object, JavaScript throws a TypeError.

Symbol.toStringTag does a different job. It sets the word inside a label like [object Map]. You see that label when you call Object.prototype.toString.call(value). It does not change what a template literal prints.

const report = { [Symbol.toStringTag]: "Report" };
console.log(Object.prototype.toString.call(report));

Line 1 makes report with the tag "Report". Line 2 asks for the label and prints [object Report]. Without the tag, it would print [object Object]. This helps in logs.

value instanceof Thing asks: "Was value made by Thing?" Normally it checks whether Thing.prototype is in the value's prototype chain. The prototype chain is the list of objects JavaScript searches when it looks up a property.

But first, instanceof checks the right side for a method at Symbol.hasInstance. If it finds one, it calls Thing[Symbol.hasInstance](value) and uses that answer instead.

class Adult {
  static [Symbol.hasInstance](user) { return user.age >= 18; }
}
console.log({ age: 20 } instanceof Adult);

Line 2 is a static method, so it belongs to the class Adult itself. It returns true when the age is 18 or more. Line 4 tests a plain object, { age: 20 }. That object was never made by Adult. Still, instanceof calls the method, and it prints true.

Symbol.species answers a different question. Some array methods, like map(), make a new array. If you call them on a subclass of Array, what kind of object should they make? A subclass is a class made with extends. A subclass can use Symbol.species to say: "Make a plain Array instead."

This hook exists so older code keeps working. New code should avoid it. It makes code harder to check for safety, and harder for JavaScript engines to speed up.

class Notes extends Array {
  static get [Symbol.species]() { return Array; }
}
const notes = new Notes("read", "write");
console.log(notes.map((note) => note.toUpperCase()) instanceof Notes);

Line 1 makes Notes, a subclass of Array. Line 2 is a static get: a getter on the class, which runs when the key is read. It returns Array. On line 5, map reads this key to choose what to make. So the new array is a plain Array, and line 5 prints false.

1class Bag extends Array {2  static get [Symbol.species]() {3    return Array;4  }5}6 7const bag = new Bag("notebook", "pencil");8const result = bag.map((item) => item.toUpperCase());9console.log(result instanceof Bag);10console.log(result instanceof Array);

[].concat(value) joins values into a new array. It has its own rule:

• An array is opened up: each of its items is added one by one.
• A plain object is added as one item.

Symbol.isConcatSpreadable changes that rule for one value. Set it to true on an array-like object, and concat opens it up. An array-like object has number keys, like 0 and 1, and a length. Set it to false on an array, and concat adds the whole array as one item.

const row = {
  0: "tea", 1: "cake", length: 2,
  [Symbol.isConcatSpreadable]: true,
};
console.log(["menu"].concat(row).join(" / "));

Line 2 gives row the keys 0 and 1 and a length of 2. Line 3 sets the flag to true. So on line 5, concat adds tea and cake one by one, and it prints menu / tea / cake. Without the flag, it would add the whole object as one item.

Symbol.unscopables is mostly history. Very old code used a with statement, which lets you write includes instead of list.includes. Strict mode does not allow with, and this site never runs it.

When new array methods like includes were added, old with code could break. So arrays keep a list of names that with must skip. That list is at Array.prototype[Symbol.unscopables].

1const hiddenFromWith = Array.prototype[Symbol.unscopables];2console.log(hiddenFromWith.includes);3console.log(hiddenFromWith.find);4console.log(hiddenFromWith.at);

const hidden = Array.prototype[Symbol.unscopables];
console.log(hidden.includes);
console.log(hidden.at);

Line 1 reads the list from the array prototype. Lines 2 and 3 check two names, and both print true: old with code skips includes and at. Don't write with in new code. You only need this symbol when you read old code.

A regex (regular expression) is a pattern for finding text, like /cat/. You usually pass one to string methods such as replace. But you can pass your own object instead. Each of these string methods looks for a matching symbol method on the object you pass in:

• match calls Symbol.match.
• matchAll calls Symbol.matchAll.
• replace calls Symbol.replace.
• search calls Symbol.search.
• split calls Symbol.split.

If the method is there, the string hands the work to it. In this lesson, an object like that is called a matcher.

const matcher = { [Symbol.match](text) { return text.includes("cat") ? "found" : "missing"; } };
console.log("cat nap".match(matcher));

Line 1 makes a matcher with a Symbol.match method. It returns "found" if the text has cat in it. Line 2 calls "cat nap".match(matcher). The string calls the method, so it prints found. The other four methods work the same way. Each example below uses one.

const matcher = { flags: "g", [Symbol.matchAll](text) { return text.matchAll(/cat/g); } };
console.log([..."cat cat".matchAll(matcher)].length);

The matcher's method finds every cat with the real regex /cat/g. The g means "global": find every match, not just the first. The matcher also needs flags: "g", because matchAll checks for it first. Line 2 spreads the two matches into an array and prints its length, 2.

const matcher = { [Symbol.replace](text, replacement) { return text.replaceAll("cat", replacement); } };
console.log("cat nap".replace(matcher, "dog"));

The method gets two arguments: the whole text, "cat nap", and the new word, "dog". It swaps every cat for dog, so line 2 prints dog nap.

const matcher = { [Symbol.search](text) { return text.indexOf("cat"); } };
console.log("scatter".search(matcher));

The method returns the position where cat starts in "scatter". Positions start at 0, so s is 0 and c is 1. Line 2 prints 1. Each hook works on its own, so you only write the ones you need.

const matcher = { [Symbol.split](text) { return text.split("/"); } };
console.log("tea/cake".split(matcher).join(" + "));

The method cuts the text at each /, so "tea/cake" becomes ["tea", "cake"]. Line 2 joins the pieces and prints tea + cake. This method runs only for split, never for search or replace.

1const matcher = {2  needle: "cat",3  flags: "g",4  [Symbol.match](text) { return text.includes(this.needle); },5  [Symbol.matchAll](text) { return text.matchAll(/cat/g); },6  [Symbol.replace](text, replacement) { return text.replaceAll(this.needle, replacement); },7  [Symbol.search](text) { return text.indexOf(this.needle); },8  [Symbol.split](text) { return text.split(this.needle); },9};10 11"cat nap cat".replace(matcher, "dog");

Some things must be cleaned up when you finish with them, even if your code fails halfway. Examples are an open file, a lock, or a subscription. JavaScript gives that cleanup method a standard key:

• Symbol.dispose for cleanup that finishes right away.
• Symbol.asyncDispose for cleanup you must wait for.

1const rental = {2  open: true,3  [Symbol.dispose]() {4    this.open = false;5    console.log("returned rental");6  },7};8 9try {10  console.log("using rental");11  throw new Error("trip failed");12} finally {13  rental[Symbol.dispose]();14}15console.log(rental.open);

In the lab's code, line 3 is the cleanup method. It sets open to false and prints returned rental. Line 10 prints using rental, then line 11 throws an error. A finally block always runs, even after an error, so line 13 calls the cleanup method. Then the error goes on, so line 15 never runs.

JavaScript also has newer tools that call the cleanup method for you:

• the using and await using keywords
• DisposableStack and AsyncDisposableStack, which collect several cleanups

At the time of writing, these are new. Some browsers and servers have the symbols but not these tools. So check that a tool exists before you use it. This is called feature detection. In a library, keep a try/finally version too, because it works everywhere.

Where you will use this

You will read these hooks more often than you write them. They show up in custom lists, form-checking libraries, price and date objects, data that arrives in pages, test helpers, and cleanup code. Before you write one, ask: "Do I want built-in code, like spread or a template literal, to use this object?"

• Use Symbol.iterator when the value is a list of things.
• Use Symbol.asyncIterator when the values arrive later.
• Use the string method hooks for small matcher objects.
• Use Symbol.toPrimitive only when the result is obvious, and write down what it does.
• Use the dispose hooks for cleanup, with feature detection and a try/finally version.

class Cart {
  constructor(items) { this.items = items; }
  get [Symbol.toStringTag]() { return "Cart"; }
  *[Symbol.iterator]() { yield* this.items; }
  [Symbol.toPrimitive](hint) { return hint === "number" ? this.items.length : `Cart(${this.items.length})`; }
}
const cart = new Cart(["tea", "bread"]);
console.log([...cart].join(", "));
console.log(Object.prototype.toString.call(cart));
console.log(+cart);

Cart is a normal class that keeps its things in items. It has three hooks:

• Line 3 is a getter for the tag, so line 9 prints [object Cart].
• Line 4 is the loop hook, so the spread on line 8 prints tea, bread.
• Line 5 is the primitive hook. The + in front of cart on line 10 sends the "number" hint, so it prints 2, the number of items.

Each hook serves one built-in operation. The class still keeps its data in a plain items property that you can read directly.

Common misconceptions

Each row of this table shows something that is easy to get wrong, and what is true instead.

Key takeaways

• Well-known symbols are built-in keys. Built-in code looks for methods at these keys and calls them.
• Symbol.iterator lets for...of and spread read an object. Symbol.asyncIterator does the same for for await...of.
• Symbol.toPrimitive gets the hint string, number, or default. Symbol.toStringTag sets the word in [object Tag].
• Symbol.hasInstance, Symbol.species, Symbol.isConcatSpreadable, and Symbol.unscopables each change one small behavior. You rarely need them.
• The string method hooks and the dispose hooks are useful. Check that dispose tools exist, and keep hooks unsurprising.

Up next: Decorators, reusable wrappers for classes, methods, and fields.