Array.prototype.values()
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since May 2018.
Thevalues() method ofArray instances returns a newarray iterator object that iterates the value of each item in the array.
Try it
const array = ["a", "b", "c"];const iterator = array.values();for (const value of iterator) { console.log(value);}// Expected output: "a"// Expected output: "b"// Expected output: "c"Syntax
values()Parameters
None.
Return value
A newiterable iterator object.
Description
Array.prototype.values() is the default implementation ofArray.prototype[Symbol.iterator]().
Array.prototype.values === Array.prototype[Symbol.iterator]; // trueWhen used onsparse arrays, thevalues() method iterates empty slots as if they have the valueundefined.
Thevalues() method isgeneric. It only expects thethis value to have alength property and integer-keyed properties.
Examples
Iteration using for...of loop
Becausevalues() returns an iterable iterator, you can use afor...of loop to iterate it.
const arr = ["a", "b", "c", "d", "e"];const iterator = arr.values();for (const letter of iterator) { console.log(letter);} // "a" "b" "c" "d" "e"Iteration using next()
Because the return value is also an iterator, you can directly call itsnext() method.
const arr = ["a", "b", "c", "d", "e"];const iterator = arr.values();iterator.next(); // { value: "a", done: false }iterator.next(); // { value: "b", done: false }iterator.next(); // { value: "c", done: false }iterator.next(); // { value: "d", done: false }iterator.next(); // { value: "e", done: false }iterator.next(); // { value: undefined, done: true }console.log(iterator.next().value); // undefinedReusing the iterable
Warning:The array iterator object should be a one-time use object. Do not reuse it.
The iterable returned fromvalues() is not reusable. Whennext().done = true orcurrentIndex > length,thefor...of loop ends, and further iterating it has no effect.
const arr = ["a", "b", "c", "d", "e"];const values = arr.values();for (const letter of values) { console.log(letter);}// "a" "b" "c" "d" "e"for (const letter of values) { console.log(letter);}// undefinedIf you use abreak statement to end the iteration early, the iterator can resume from the current position when continuing to iterate it.
const arr = ["a", "b", "c", "d", "e"];const values = arr.values();for (const letter of values) { console.log(letter); if (letter === "b") { break; }}// "a" "b"for (const letter of values) { console.log(letter);}// "c" "d" "e"Mutations during iteration
There are no values stored in the array iterator object returned fromvalues(); instead, it stores the address of the array used in its creation, and reads the currently visited index on each iteration. Therefore, its iteration output depends on the value stored in that index at the time of stepping. If the values in the array changed, the array iterator object's values change too.
const arr = ["a", "b", "c", "d", "e"];const iterator = arr.values();console.log(iterator); // Array Iterator { }console.log(iterator.next().value); // "a"arr[1] = "n";console.log(iterator.next().value); // "n"Unlikeiterative methods, the array iterator object does not save the array's length at the time of its creation, but reads it once on each iteration. Therefore, if the array grows during iteration, the iterator will visit the new elements too. This may lead to infinite loops.
const arr = [1, 2, 3];for (const e of arr) { arr.push(e * 10);}// RangeError: invalid array lengthIterating sparse arrays
values() will visit empty slots as if they areundefined.
for (const element of [, "a"].values()) { console.log(element);}// undefined// 'a'Calling values() on non-array objects
Thevalues() method reads thelength property ofthis and then accesses each property whose key is a nonnegative integer less thanlength.
const arrayLike = { length: 3, 0: "a", 1: "b", 2: "c", 3: "d", // ignored by values() since length is 3};for (const entry of Array.prototype.values.call(arrayLike)) { console.log(entry);}// a// b// cSpecifications
| Specification |
|---|
| ECMAScript® 2026 Language Specification # sec-array.prototype.values |