JavaScript Reference ยท Iterators, Generators and Symbols
Well-known symbols
Overview of the well-known symbols such as Symbol.asyncIterator, hasInstance, toStringTag, isConcatSpreadable and species, with live examples of each hook.
Well-known symbols are built-in symbols stored as properties of the Symbol constructor. Each one names a hook: if your object defines a method or value under that key, a built-in operation notices it and changes its behavior. They let ordinary objects take part in the language's own protocols without any special syntax.
This page is a concept page. It lists the symbols, explains what each one controls and shows the most useful ones in action. None of them is registered in the global symbol registry, so Symbol.keyFor() returns undefined for all of them.
Try it
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
The symbols
| Symbol | Used by | What it controls |
|---|---|---|
Symbol.iterator |
for...of, spread, destructuring |
A method returning an iterator. See Symbol.iterator. |
Symbol.asyncIterator |
for await...of |
A method returning an async iterator. |
Symbol.hasInstance |
instanceof |
x instanceof C calls C[Symbol.hasInstance](x) and converts the result to a boolean. |
Symbol.toPrimitive |
Type conversion | Converts an object to a primitive. See Symbol.toPrimitive. |
Symbol.toStringTag |
Object.prototype.toString() |
The tag in [object Tag]. Built-ins such as Map and Promise set it. |
Symbol.isConcatSpreadable |
Array.prototype.concat() |
Whether an object is flattened (true) or added as one element (false). |
Symbol.species |
Methods that create a new instance of a subclass | A static getter naming the constructor to use for derived objects (for example in Array and Promise subclasses). |
Symbol.match, matchAll, replace, search, split |
String.prototype methods |
Let an object act like a regular expression for match(), matchAll(), replace(), search() and split(). |
Symbol.unscopables |
with statements |
Names to hide from with lookups. Mostly historical. |
Symbol.dispose, Symbol.asyncDispose |
using declarations |
Cleanup methods for explicit resource management. Recent; check a compatibility table. |
Usage notes
- They are keys, not values you call. Write
obj[Symbol.hasInstance] = ...or use a computed method name,[Symbol.iterator]() {}. - Most of them are rarely needed.
Symbol.iterator,Symbol.asyncIteratorandSymbol.toStringTagcover the large majority of real code. Symbol.hasInstanceis looked up on the right-hand side, so for classes you define it as astaticmethod. A normal method would apply to instances, not to the class.toStringTagis a debugging aid. It changesObject.prototype.toString.call(x), nottypeofand notinstanceof.Symbol.speciesis easy to misuse. It is mainly for library authors who subclass built-ins; most code never touches it.- The regexp-like symbols make custom matchers possible:
"text".split(obj)callsobj[Symbol.split]("text", limit)when the method exists. - Overriding a built-in's symbol affects everything that uses it, so prefer defining the symbol on your own classes rather than on prototypes you do not own.
- Property enumeration. Symbol keys are skipped by
Object.keys(),for...inandJSON.stringify();Reflect.ownKeys()includes them.
Browser support
The core symbols (iterator, asyncIterator, hasInstance, toPrimitive, toStringTag, isConcatSpreadable, species and the regexp ones) are supported in every current browser. Symbol.dispose and Symbol.asyncDispose are recent, so check a compatibility table before using them.