Loop (for each) over an array in JavaScript
arrays, foreach, iteration, javascript, loops
Solution
TL;DR
Your best bets are usually
- a `for-of` loop (ES2015+ only; spec | MDN) - simple and `async`-friendly
for (const element of theArray) {
// ...use `element`...
}
- `forEach` (ES5+ only; spec | MDN) (or its relatives `some` and such) - not `async`-friendly (but see details)
theArray.forEach(element => {
// ...use `element`...
});
- a simple old-fashioned `for` loop - `async`-friendly
for (let index = 0; index < theArray.length; ++index) {
const element = theArray[index];
// ...use `element`...
}
- (rarely) `for-in` with safeguards - `async`-friendly
for (const propertyName in theArray) {
if (/*...is an array element property (see below)...*/) {
const element = theArray[propertyName];
// ...use `element`...
}
}
Some quick "don't"s:
- Don't use `for-in` unless you use it with safeguards or are at least aware of why it might bite you.
- Don't use `map` if you're not using its return value. (There's sadly someone out there teaching `map` [spec / MDN] as though it were `forEach` — but as I write on my blog, that's not what it's for. If you aren't using the array it creates, don't use `map`.)
- Don't use `forEach` if the callback does asynchronous work and you want the `forEach` to wait until that work is done (because it won't).
But there's lots more to explore, read on...
JavaScript has powerful semantics for looping through arrays and array-like objects. I've split the answer into two parts: Options for genuine arrays, and options for things that are just array-like, such as the `arguments` object, other iterable objects (ES2015+), DOM collections, and so on.
Okay, let's look at our options:
For Actual Arrays
You have five options (two supported basically forever, another added by ECMAScript 5 ["ES5"], and two more added in ECMAScript 2015 ("ES2015", aka "ES6"):
- Use `for-of` (use an iterator implicitly) (ES2015+)
- Use `forEach` and related (ES5+)
- Use a simple `for` loop
- Use `for-in` correctly
- Use an iterator explicitly (ES2015+)
(You can see those old specs here: ES5, ES2015, but both have been superceded; the current editor's draft is always here.)
Details:
1. Use `for-of` (use an iterator implicitly) (ES2015+)
ES2015 added iterators and iterables to JavaScript. Arrays are iterable (so are strings, `Map`s, and `Set`s, as well as DOM collections and lists, as you'll see later). Iterable objects provide iterators for their values. The new `for-of` statement loops through the values returned by an iterator:
const a = ["a", "b", "c"];
for (const element of a) { // You can use `let` instead of `const` if you like
console.log(element);
}
// a
// b
// c
It doesn't get simpler than that! Under the covers, that gets an iterator from the array and loops through the values the iterator returns. The iterator provided by arrays provides the values of the array elements, in order beginning to end.
Notice how `element` is scoped to each loop iteration; trying to use `element` after the end of the loop would fail because it doesn't exist outside the loop body.
In theory, a `for-of` loop involves several function calls (one to get the iterator, then one to get each value from it). Even when that's true, it's nothing to worry about, function calls are very cheap in modern JavaScript engines (it bothered me for `forEach` [below] until I looked into it; details). But additionally, JavaScript engines optimize those calls away (in performance-critical code) when dealing with native iterators for things like arrays.
`for-of` is entirely `async`-friendly. If you need the work in a loop body to be done in series (not in parallel), an `await` in the loop body will wait for the promise to settle before continuing. Here's a silly example:
function delay(ms) {
return new Promise(resolve => {
setTimeout(resolve, ms);
});
}
async function showSlowly(messages) {
for (const message of messages) {
await delay(400);
console.log(message);
}
}
showSlowly([
"So", "long", "and", "thanks", "for", "all", "the", "fish!"
]);
// `.catch` omitted because we know it never rejects
Note how the words appear with a delay before each one.
It's a matter of coding style, but `for-of` is the first thing I reach for when looping through anything iterable.
2. Use `forEach` and related
In any even vaguely-modern environment (so, not IE8) where you have access to the `Array` features added by ES5, you can use `forEach` (spec | MDN) if you're only dealing with synchronous code (or you don't need to wait for an asynchronous process to finish during the loop):
const a = ["a", "b", "c"];
a.forEach((element) => {
console.log(element);
});
`forEach` accepts a callback function and, optionally, a value to use as `this` when calling that callback (not used above). The callback is called for each element in the array, in order, skipping non-existent elements in sparse arrays. Although I only used one parameter above, the callback is called with three arguments: The element for that iteration, the index of that element, and a reference to the array you're iterating over (in case your function doesn't already have it handy).
Like `for-of`, `forEach` has the advantage that you don't have to declare indexing and value variables in the containing scope; in this case, they're supplied as arguments to the iteration function, and so nicely scoped to just that iteration.
Unlike `for-of`, `forEach` has the disadvantage that it doesn't understand `async` functions and `await`. If you use an `async` function as the callback, `forEach` does not wait for that function's promise to settle before continuing. Here's the `async` example from `for-of` using `forEach` instead — notice how there's an initial delay, but then all the text appears right away instead of waiting:
function delay(ms) {
return new Promise(resolve => {
setTimeout(resolve, ms);
});
}
async function showSlowly(messages) {
// INCORRECT, doesn't wait before continuing,
// doesn't handle promise rejections
messages.forEach(async message => {
await delay(400);
console.log(message);
});
}
showSlowly([
"So", "long", "and", "thanks", "for", "all", "the", "fish!"
]);
// `.catch` omitted because we know it never rejects
`forEach` is the "loop through them all" function, but ES5 defined several other useful "work your way through the array and do things" functions, including:
- `every` (spec | MDN) - stops looping the first time the callback returns a falsy value
- `some` (spec | MDN) - stops looping the first time the callback returns a truthy value
- `filter` (spec | MDN) - creates a new array including elements where the callback returns a truthy value, omitting the ones where it doesn't
- `map` (spec | MDN) - creates a new array from the values returned by the callback
- `reduce` (spec | MDN) - builds up a value by repeatedly calling the callback, passing in previous values; see the spec for the details
- `reduceRight` (spec | MDN) - like `reduce`, but works in descending rather than ascending order
As with `forEach`, if you use an `async` function as your callback, none of those waits for the function's promise to settle. That means:
- Using an `async` function callback is never appropriate with `every`, `some`, and `filter` since they will treat the returned promise as though it were a truthy value; they don't wait for the promise to settle and then use the fulfillment value.
- Using an `async` function callback is often appropriate with `map`, if the goal is to turn an array of something into an array of promises, perhaps for passing to one of the promise combinator functions (`Promise.all`, `Promise.race`, `promise.allSettled`, or `Promise.any`).
- Using an `async` function callback is rarely appropriate with `reduce` or `reduceRight`, because (again) the callback will always return a promise. But there is an idiom of building a chain of promises from an array that uses `reduce` (`const promise = array.reduce((p, element) => p.then(/*...something using `element`...*/));`), but usually in those cases a `for-of` or `for` loop in an `async` function will be clearer and easier to debug.
3. Use a simple `for` loop
Sometimes the old ways are the best:
const a = ["a", "b", "c"];
for (let index = 0; index < a.length; ++index) {
const element = a[index];
console.log(element);
}
If the length of the array won't change during the loop, and it's in highly performance-sensitive code, a slightly more complicated version grabbing the length up front might be a tiny bit faster:
const a = ["a", "b", "c"];
for (let index = 0, len = a.length; index < len; ++index) {
const element = a[index];
console.log(element);
}
And/or counting backward:
const a = ["a", "b", "c"];
for (let index = a.length - 1; index >= 0; --index) {
const element = a[index];
console.log(element);
}
But with modern JavaScript engines, it's rare you need to eke out that last bit of juice.
Before ES2015, the loop variable had to exist in the containing scope, because `var` only has function-level scope, not block-level scope. But as you saw in the examples above, you can use `let` within the `for` to scope the variables to just the loop. And when you do that, the `index` variable is recreated for each loop iteration, meaning closures created in the loop body keep a reference to the `index` for that specific iteration, which solves the old "closures in loops" problem:
// (The `NodeList` from `querySelectorAll` is array-like)
const divs = document.querySelectorAll("div");
for (let index = 0; index < divs.length; ++index) {
divs[index].addEventListener('click', e => {
console.log("Index is: " + index);
});
}
<div>zero</div>
<div>one</div>
<div>two</div>
<div>three</div>
<div>four</div>
In the above, you get "Index is: 0" if you click the first and "Index is: 4" if you click the last. This does not work if you use `var` instead of `let` (you'd always see "Index is: 5").
Like `for-of`, `for` loops work well in `async` functions. Here's the earlier example using a `for` loop:
function delay(ms) {
return new Promise(resolve => {
setTimeout(resolve, ms);
});
}
async function showSlowly(messages) {
for (let i = 0; i < messages.length; ++i) {
const message = messages[i];
await delay(400);
console.log(message);
}
}
showSlowly([
"So", "long", "and", "thanks", "for", "all", "the", "fish!"
]);
// `.catch` omitted because we know it never rejects
4. Use `for-in` correctly
`for-in` isn't for looping through arrays, it's for looping through the names of an object's properties. It does often seem to work for looping through arrays as a by-product of the fact that arrays are objects, but it doesn't just loop through the array indexes, it loops through all enumerable properties of the object (including inherited ones). (It also used to be that the order wasn't specified; it is now [details in this other answer], but even though the order is specified now, the rules are complex, there are exceptions, and relying on the order is not best practice.)
The only real use cases for `for-in` on an array are:
- It's a sparse array with massive gaps in it, or
- You're using non-element properties on the array object and you want to include them in the loop
Looking only at that first example: You can use `for-in` to visit those sparse array elements if you use appropriate safeguards:
// `a` is a sparse array
const a = [];
a[0] = "a";
a[10] = "b";
a[10000] = "c";
for (const name in a) {
if (Object.hasOwn(a, name) && // These checks are
/^0$|^[1-9]\d*$/.test(name) && // explained
name <= 4294967294 // below
) {
const element = a[name];
console.log(a[name]);
}
}
Note the three checks:
That the object has its own property by that name (not one it inherits from its prototype; this check is also often written as `a.hasOwnProperty(name)` but ES2022 adds `Object.hasOwn` which can be more reliable), and
That the name is all decimal digits (e.g., normal string form, not scientific notation), and
That the name's value when coerced to a number is <= 2^32 - 2 (which is 4,294,967,294). Where does that number come from? It's part of the definition of an array index in the specification. Other numbers (non-integers, negative numbers, numbers greater than 2^32 - 2) are not array indexes. The reason it's 2^32 - 2 is that that makes the greatest index value one lower than 2^32 - 1, which is the maximum value an array's `length` can have. (E.g., an array's length fits in a 32-bit unsigned integer.)
...although with that said, most code only does the `hasOwnProperty` check.
You wouldn't do that in inline code, of course. You'd write a utility function. Perhaps:
// Utility function for antiquated environments without `forEach`
const hasOwn = Object.prototype.hasOwnProperty.call.bind(Object.prototype.hasOwnProperty);
const rexNum = /^0$|^[1-9]\d*$/;
function sparseEach(array, callback, thisArg) {
for (const name in array) {
const index = +name;
if (hasOwn(a, name) &&
rexNum.test(name) &&
index <= 4294967294
) {
callback.call(thisArg, array[name], index, array);
}
}
}
const a = [];
a[5] = "five";
a[10] = "ten";
a[100000] = "one hundred thousand";
a.b = "bee";
sparseEach(a, (value, index) => {
console.log("Value at " + index + " is " + value);
});
Like `for`, `for-in` works well in asynchronous functions if the work within it needs to be done in series.
function delay(ms) {
return new Promise(resolve => {
setTimeout(resolve, ms);
});
}
async function showSlowly(messages) {
for (const name in messages) {
if (messages.hasOwnProperty(name)) { // Almost always this is the only check people do
const message = messages[name];
await delay(400);
console.log(message);
}
}
}
showSlowly([
"So", "long", "and", "thanks", "for", "all", "the", "fish!"
]);
// `.catch` omitted because we know it never rejects
5. Use an iterator explicitly (ES2015+)
`for-of` uses an iterator implicitly, doing all the scut work for you. Sometimes, you might want to use an iterator explicitly. It looks like this:
const a = ["a", "b", "c"];
const it = a.values(); // Or `const it = a[Symbol.iterator]();` if you like
let entry;
while (!(entry = it.next()).done) {
const element = entry.value;
console.log(element);
}
An iterator is an object matching the Iterator definition in the specification. Its `next` method returns a new result object each time you call it. The result object has a property, `done`, telling us whether it's done, and a property `value` with the value for that iteration. (`done` is optional if it would be `false`, `value` is optional if it would be `undefined`.)
What you get for `value` varies depending on the iterator. On arrays, the default iterator provides the value of each array element (`"a"`, `"b"`, and `"c"` in the example earlier). Arrays also have three other methods that return iterators:
- `values()`: This is an alias for the `[Symbol.iterator]` method that returns the default iterator.
- `keys()`: Returns an iterator that provides each key (index) in the array. In the example above, it would provide `0`, then `1`, then `2` (as numbers, not strings). (Also note that in a sparse array, it will include indexes for elements that don't exist.)
- `entries()`: Returns an iterator that provides `[key, value]` arrays.
Since iterator objects don't advance until you call `next`, they work well in `async` function loops. Here's the earlier `for-of` example using the iterator explicitly:
function delay(ms) {
return new Promise(resolve => {
setTimeout(resolve, ms);
});
}
async function showSlowly(messages) {
const it = messages.values()
while (!(entry = it.next()).done) {
await delay(400);
const element = entry.value;
console.log(element);
}
}
showSlowly([
"So", "long", "and", "thanks", "for", "all", "the", "fish!"
]);
// `.catch` omitted because we know it never rejects
For Array-Like Objects
Aside from true arrays, there are also array-like objects that have a `length` property and properties with all-digits names: `NodeList` instances, `HTMLCollection` instances, the `arguments` object, etc. How do we loop through their contents?
Use most of the options above
At least some, and possibly most or even all, of the array approaches above apply equally well to array-like objects:
Use `for-of` (use an iterator implicitly) (ES2015+)
`for-of` uses the iterator provided by the object (if any). That includes host-provided objects (like DOM collections and lists). For instance, `HTMLCollection` instances from `getElementsByXYZ` methods and `NodeList`s instances from `querySelectorAll` both support iteration. (This is defined quite subtly by the HTML and DOM specifications. Basically, any object with `length` and indexed access is automatically iterable. It doesn't have to be marked `iterable`; that is used only for collections that, in addition to being iterable, support `forEach`, `values`, `keys`, and `entries` methods. `NodeList` does; `HTMLCollection` doesn't, but both are iterable.)
Here's an example of looping through `div` elements:
const divs = document.querySelectorAll("div");
for (const div of divs) {
div.textContent = Math.random();
}
<div>zero</div>
<div>one</div>
<div>two</div>
<div>three</div>
<div>four</div>
Use `forEach` and related (ES5+)
The various functions on `Array.prototype` are "intentionally generic" and can be used on array-like objects via `Function#call` (spec | MDN) or `Function#apply` (spec | MDN). (If you have to deal with IE8 or earlier [ouch], see the "Caveat for host-provided objects" at the end of this answer, but it's not an issue with vaguely-modern browsers.)
Suppose you wanted to use `forEach` on a `Node`'s `childNodes` collection (which, being an `HTMLCollection`, doesn't have `forEach` natively). You'd do this:
Array.prototype.forEach.call(node.childNodes, (child) => {
// Do something with `child`
});
(Note, though, that you could just use `for-of` on `node.childNodes`.)
If you're going to do that a lot, you might want to grab a copy of the function reference into a variable for reuse, e.g.:
// (This is all presumably in a module or some scoping function)
const forEach = Array.prototype.forEach.call.bind(Array.prototype.forEach);
// Then later...
forEach(node.childNodes, (child) => {
// Do something with `child`
});
Use a simple `for` loop
Perhaps obviously, a simple `for` loop works for array-like objects.
Use an iterator explicitly (ES2015+)
See #1.
You may be able to get away with `for-in` (with safeguards), but with all of these more appropriate options, there's no reason to try.
Create a true array
Other times, you may want to convert an array-like object into a true array. Doing that is surprisingly easy:
Use `Array.from`
`Array.from` (spec) | (MDN) (ES2015+, but easily polyfilled) creates an array from an array-like object, optionally passing the entries through a mapping function first. So:
const divs = Array.from(document.querySelectorAll("div"));
...takes the `NodeList` from `querySelectorAll` and makes an array from it.
The mapping function is handy if you were going to map the contents in some way. For instance, if you wanted to get an array of the tag names of the elements with a given class:
// Typical use (with an arrow function):
const divs = Array.from(document.querySelectorAll(".some-class"), element => element.tagName);
// Traditional function (since `Array.from` can be polyfilled):
var divs = Array.from(document.querySelectorAll(".some-class"), function(element) {
return element.tagName;
});
Use spread syntax (`...`)
It's also possible to use ES2015's spread syntax. Like `for-of`, this uses the iterator provided by the object (see #1 in the previous section):
const trueArray = [...iterableObject];
So for instance, if we want to convert a `NodeList` into a true array, with spread syntax this becomes quite succinct:
const divs = [...document.querySelectorAll("div")];
Use the `slice` method of arrays
We can use the `slice` method of arrays, which like the other methods mentioned above is "intentionally generic" and so can be used with array-like objects, like this:
const trueArray = Array.prototype.slice.call(arrayLikeObject);
So for instance, if we want to convert a `NodeList` into a true array, we could do this:
const divs = Array.prototype.slice.call(document.querySelectorAll("div"));
(If you still have to handle IE8 [ouch], will fail; IE8 didn't let you use host-provided objects as `this` like that.)
Caveat for host-provided objects
If you use `Array.prototype` functions with host-provided array-like objects (for example, DOM collections and such provided by the browser rather than the JavaScript engine), obsolete browsers like IE8 didn't necessarily handle that way, so if you have to support them, be sure to test in your target environments. But it's not an issue with vaguely-modern browsers. (For non-browser environments, naturally it'll depend on the environment.)
Problem
How can I loop through all the entries in an array using JavaScript?
Related problems
- Why is using "for...in" for array iteration a bad idea?
- How do I loop through or enumerate a JavaScript object?
- Does ES6 introduce a well-defined order of enumeration for object properties?
- Short circuit Array.forEach like calling break
- Is micro-optimization worth the time?
- Loop through an array in JavaScript
- C for loop indexing: is forward-indexing faster in new CPUs?