Symbol.iterator

The well-known Symbol.iterator symbol specifies the default iterator for an object. Used by for...of.

Description

Whenever an object needs to be iterated (such as at the beginning of a for..of loop), its @@iterator method is called with no arguments, and the returned iterator is used to obtain the values to be iterated.

Some built-in types have a default iteration behavior, while other types (such as Object) do not. The built-in types with a @@iterator method are:

• Array.prototype[@@iterator]()
• TypedArray.prototype[@@iterator]()
• String.prototype[@@iterator]()
• Map.prototype[@@iterator]()
• Set.prototype[@@iterator]()

See also Iteration protocols for more information.

Examples

User-defined iterables

We can make our own iterables like this:

var myIterable = {}
myIterable[Symbol.iterator] = function* () {
    yield 1;
    yield 2;
    yield 3;
};
[...myIterable] // [1, 2, 3]

Or iterables can be defined directly inside a class or object using a computed property:

class Foo {
  *[Symbol.iterator] () {
    yield 1;
    yield 2;
    yield 3;
  }
}

const someObj = {
  *[Symbol.iterator] () {
    yield 'a';
    yield 'b';
  }
}

[...new Foo] // [ 1, 2, 3 ]
[...someObj] // [ 'a', 'b' ]

Non-well-formed iterables

If an iterable's @@iterator method does not return an iterator object, then it is a non-well-formed iterable. Using it as such is likely to result in runtime exceptions or buggy behavior:

var nonWellFormedIterable = {}
nonWellFormedIterable[Symbol.iterator] = () => 1
[...nonWellFormedIterable] // TypeError: [] is not a function

Specifications

Browser compatibilityUpdate compatibility data on GitHub

See also

• Iteration protocols
• Array.prototype[@@iterator]()
• TypedArray.prototype[@@iterator]()
• String.prototype[@@iterator]()
• Map.prototype[@@iterator]()
• Set.prototype[@@iterator]()