Skip to content
Tutorials Center
My learning

Topics

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

JS toStringTag and hasInstance

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS isConcatSpreadable and asyncIterator

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.asyncIterator and Symbol.toStringTag cover the large majority of real code.
  • Symbol.hasInstance is looked up on the right-hand side, so for classes you define it as a static method. A normal method would apply to instances, not to the class.
  • toStringTag is a debugging aid. It changes Object.prototype.toString.call(x), not typeof and not instanceof.
  • Symbol.species is 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) calls obj[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...in and JSON.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.