The forEach() method executes a provided function once for each array element.

The source for this interactive example is stored in a GitHub repository. If you"d like to contribute to the interactive examples project, please clone https://github.com/mdn/interactive-examples and send us a pull request.

Syntax

arr .forEach(callback(currentValue [, index [, array]]) [, thisArg ])

Parameters

callback Function to execute on each element. It accepts between one and three arguments: currentValue The current element being processed in the array. index Optional The index currentValue in the array. array Optional The array forEach() was called upon. thisArg Optional Value to use as this when executing callback .

Return value

Description

forEach() calls a provided callback function once for each element in an array in ascending order. It is not invoked for index properties that have been deleted or are uninitialized. (For sparse arrays, .)

callback is invoked with three arguments:

1. the value of the element
2. the index of the element
3. the Array object being traversed

If a thisArg parameter is provided to forEach() , it will be used as callback"s this value. The thisArg value ultimately observable by callback is determined according to the usual rules for determining the this seen by a function .

The range of elements processed by forEach() is set before the first invocation of callback . Elements which are appended to the array after the call to forEach() begins will not be visited by callback . If existing elements of the array are changed or deleted, their value as passed to callback will be the value at the time forEach() visits them; elements that are deleted before being visited are not visited. If elements that are already visited are removed (e.g. using shift()) during the iteration, later elements will be skipped. (See this example, below .)

forEach() executes the callback function once for each array element; unlike map() or reduce() it always returns the value undefined and is not chainable. The typical use case is to execute side effects at the end of a chain.

forEach() does not mutate the array on which it is called. (However, callback may do so)

There is no way to stop or break a forEach() loop other than by throwing an exception. If you need such behavior, the forEach() method is the wrong tool.

Early termination may be accomplished with:

Array methods: every() , some() , find() , and findIndex() test the array elements with a predicate returning a truthy value to determine if further iteration is required.

Examples

No operation for uninitialized values (sparse arrays)

const arraySparse = let numCallbackRuns = 0 arraySparse.forEach(function(element){ console.log(element) numCallbackRuns++ }) console.log("numCallbackRuns: ", numCallbackRuns) // 1 // 3 // 7 // numCallbackRuns: 3 // comment: as you can see the missing value between 3 and 7 didn"t invoke callback function.

Converting a for loop to forEach

const items = ["item1", "item2", "item3"] const copy = // before for (let i = 0; i < items.length; i++) { copy.push(items[i]) } // after items.forEach(function(item){ copy.push(item) })

Printing the contents of an array

Note: In order to display the content of an array in the console, you can use console.table() , which prints a formatted version of the array.

The following example illustrates an alternative approach, using forEach() .

The following code logs a line for each element in an array:

Function logArrayElements(element, index, array) { console.log("a[" + index + "] = " + element) } // Notice that index 2 is skipped, since there is no item at // that position in the array... .forEach(logArrayElements) // logs: // a = 2 // a = 5 // a = 9

Using thisArg

The following (contrived) example updates an object"s properties from each entry in the array:

Function Counter() { this.sum = 0 this.count = 0 } Counter.prototype.add = function(array) { array.forEach(function(entry) { this.sum += entry ++this.count }, this) // ^---- Note } const obj = new Counter() obj.add() obj.count // 3 obj.sum // 16

Since the thisArg parameter (this) is provided to forEach() , it is passed to callback each time it"s invoked. The callback uses it as its this value.

An object copy function

The following code creates a copy of a given object.

There are different ways to create a copy of an object. The following is just one way and is presented to explain how Array.prototype.forEach() works by using ECMAScript 5 Object.* meta property functions.

Function copy(obj) { const copy = Object.create(Object.getPrototypeOf(obj)) const propNames = Object.getOwnPropertyNames(obj) propNames.forEach(function(name) { const desc = Object.getOwnPropertyDescriptor(obj, name) Object.defineProperty(copy, name, desc) }) return copy } const obj1 = { a: 1, b: 2 } const obj2 = copy(obj1) // obj2 looks like obj1 now

If the array is modified during iteration, other elements might be skipped.

The following example logs "one" , "two" , "four" .

When the entry containing the value "two" is reached, the first entry of the whole array is shifted off-resulting in all remaining entries moving up one position. Because element "four" is now at an earlier position in the array, "three" will be skipped.

forEach() does not make a copy of the array before iterating.

Let words = ["one", "two", "three", "four"] words.forEach(function(word) { console.log(word) if (word === "two") { words.shift() } }) // one // two // four

Flatten an array

The following example is only here for learning purpose. If you want to flatten an array using built-in methods you can use Array.prototype.flat() (which is expected to be part of ES2019, and is already implemented in some browsers).

/** * Flattens passed array in one dimensional array * * @params {array} arr * @returns {array} */ function flatten(arr) { const result = arr.forEach((i) => { if (Array.isArray(i)) { result.push(...flatten(i)) } else { result.push(i) } }) return result } // Usage const problem = , 8, 9]] flatten(problem) //

Note on using Promises or async functions

let ratings = let sum = 0 let sumFunction = async function (a, b) { return a + b } ratings.forEach(async function(rating) { sum = await sumFunction(sum, rating) }) console.log(sum) // Expected output: 14 // Actual output: 0

Specifications

Specification	Status	Comment
ECMAScript Latest Draft (ECMA-262)	Draft
ECMAScript 2015 (6th Edition, ECMA-262) The definition of "Array.prototype.forEach" in that specification.	Standard
ECMAScript 5.1 (ECMA-262) The definition of "Array.prototype.forEach" in that specification.	Standard	Initial definition. Implemented in JavaScript 1.6.

Browser compatibility

The compatibility table in this page is generated from structured data. If you"d like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.

Update compatibility data on GitHub

	Desktop						Mobile						Server
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet	Node.js
forEach	Chrome Full support 1	Edge Full support 12	Firefox Full support 1.5	IE Full support 9	Opera Full support Yes	Safari Full support 3	WebView Android Full support ≤37	Chrome Android Full support 18	Firefox Android Full support 4	Opera Android Full support Yes	Safari iOS Full support 1	Samsung Internet Android Full support 1.0	nodejs Full support Yes

• I. Перебор настоящих массивов
  1. Метод forEach и родственные методы
  2. Цикл for
  3. Правильное использование цикла for...in
  4. Цикл for...of (неявное использование итератора)
  5. Явное использование итератора
• II. Перебор массивоподобных объектов
  1. Использование способов перебора настоящих массивов
  2. Преобразование в настоящий массив
  3. Замечание по объектам среды исполнения

I. Перебор настоящих массивов

На данный момент есть три способа перебора элементов настоящего массива:

1. метод Array.prototype.forEach ;
2. классический цикл for ;
3. «правильно» построенный цикл for...in .

Кроме того, в скором времени, с появлением нового стандарта ECMAScript 6 (ES 6), ожидается еще два способа:

1. цикл for...of (неявное использование итератора);
2. явное использование итератора.

1. Метод forEach и родственные методы

Если ваш проект рассчитан на поддержку возможностей стандарта ECMAScript 5 (ES5), вы можете использовать одно из его нововведений - метод forEach .

Пример использования:

Var a = ["a", "b", "c"]; a.forEach(function(entry) { console.log(entry); });

В общем случае использование forEach требует подключения библиотеки эмуляции es5-shim для браузеров, не имеющих нативной поддержки этого метода. К ним относятся IE 8 и более ранние версии, которые до сих пор кое-где еще используются.

К достоинствам forEach относится то, что здесь не нужно объявлять локальные переменные для хранения индекса и значения текущего элемента массива, поскольку они автоматически передаются в функцию обратного вызова (колбек) в качестве аргументов.

Если вас беспокоят возможные затраты на вызов колбека для каждого элемента, не волнуйтесь и прочитайте это .

forEach предназначен для перебора всех элементов массива, но кроме него ES5 предлагает еще несколько полезных методов для перебора всех или некоторых элементов плюс выполнения при этом каких-либо действий с ними:

• every - возвращает true , если для каждого элемента массива колбек возвращает значение приводимое к true .
• some - возвращает true , если хотя бы для одного элемента массива колбек возвращает значение приводимое к true .
• filter - создает новый массив, включающий те элементы исходного массива, для которых колбек возвращает true .
• map - создает новый массив, состоящий из значений возращаемых колбеком.
• reduce - сводит массив к единственному значению, применяя колбек по очереди к каждому элементу массива, начиная с первого (может быть полезен для вычисления суммы элементов массива и других итоговых функций).
• reduceRight - работает аналогично reduce, но перебирает элементы в обратном порядке.

2. Цикл for

Старый добрый for рулит :

Var a = ["a", "b", "c"]; var index; for (index = 0; index < a.length; ++index) { console.log(a); }

Если длина массива неизменна в течение всего цикла, а сам цикл принадлежит критическому в плане производительности участку кода (что маловероятно), то можно использовать «более оптимальную» версию for с хранением длины массива:

Var a = ["a", "b", "c"]; var index, len; for (index = 0, len = a.length; index < len; ++index) { console.log(a); }

Теоретически этот код должен выполняться чуть быстрее, чем предыдущий.

Если порядок перебора элементов не важен, то можно пойти еще дальше в плане оптимизации и избавиться от переменной для хранения длины массива, изменив порядок перебора на обратный:

Var a = ["a", "b", "c"]; var index; for (index = a.length - 1; index >= 0; --index) { console.log(a); }

Тем не менее, в современных движках JavaScript подобные игры с оптимизацией обычно ничего не значат.

3. Правильное использование цикла for...in

Если вам посоветуют использовать цикл for...in , помните, что перебор массивов - не то, для чего он предназначен . Вопреки распространенному заблуждению цикл for...in перебирает не индексы массива, а перечислимые свойства объекта.

Тем не менее, в некоторых случаях, таких как перебор разреженных массивов , for...in может оказаться полезным, если только соблюдать при этом меры предосторожности, как показано в примере ниже:

// a - разреженный массив var a = ; a = "a"; a = "b"; a = "c"; for (var key in a) { if (a.hasOwnProperty(key) && /^0$|^d*$/.test(key) && key <= 4294967294) { console.log(a); } }

В данном примере на каждой итерации цикла выполняется две проверки:

1. то, что массив имеет собственное свойство с именем key (не наследованное из его прототипа).
2. то, что key - строка, содержащая десятичную запись целого числа, значение которого меньше 4294967294 . Откуда берется последнее число? Из определения индекса массива в ES5, из которого следует, что наибольший индекс, который может иметь элемент в массиве: (2^32 - 2) = 4294967294 .

Конечно, такие проверки отнимут лишнее время при выполнении цикла. Но в случае разреженного массива этот способ более эффективен, чем цикл for , поскольку в этом случае перебираются только те элементы, которые явно определены в массиве. Так, в примере выше будет выполнено всего 3 итерации (для индексов 0, 10 и 10000) - против 10001 в цикле for .

Чтобы не писать такой громоздкий код проверок каждый раз, когда требуется перебор массива, можно оформить его в виде отдельной функции:

Function arrayHasOwnIndex(array, key) { return array.hasOwnProperty(key) && /^0$|^d*$/.test(key) && key <= 4294967294; }

Тогда тело цикла из примера значительно сократится:

For (key in a) { if (arrayHasOwnIndex(a, key)) { console.log(a); } }

Рассмотренный выше код проверок является универсальным, подходящим для всех случаев. Но вместо него можно использовать более короткую версию, хотя формально и не совсем правильную, но, тем не менее, подходящую для большинства случаев:

For (key in a) { if (a.hasOwnProperty(key) && String(parseInt(key, 10)) === key) { console.log(a); } }

4. Цикл for...of (неявное использование итератора)

ES6, пока все еще пребывающий в статусе черновика , должен ввести в JavaScript итераторы.

Итератор - это реализуемый объектом протокол, который определяет стандартный способ получения последовательности значений (конечной или бесконечной).
Объект имеет итератор, если в нем определен метод next() - функция без аргументов, возвращающая объект с двумя свойствами:

1. done (boolean) - принимает значение true , если итератор достиг конца итерируемой последовательности. В противном случае имеет значение false .
2. value - определяет значение, возвращаемое итератором. Может быть не определено (отсутствовать), если свойство done имеет значение true .

Многие встроенные объекты, в т.ч. настоящие массивы, имеют итераторы по умолчанию. Простейший способ применения итератора в настоящих массивах - использовать новую конструкцию for...of .

Пример использования for...of:

Var val; var a = ["a", "b", "c"]; for (val of a) { console.log(val); }

В приведенном примере цикл for...of неявно вызывает итератор объекта Array для получения каждого значения массива.

5. Явное использование итератора

Итераторы можно также использовать и явно, правда, в этом случае код становится значительно сложнее, по сравнению с циклом for...of . Выглядит это примерно так:

Var a = ["a", "b", "c"]; var entry; while (!(entry = a.next()).done) { console.log(entry.value); }

II. Перебор массивоподобных объектов

Кроме настоящих массивов, в JavaScript встречаются также массивоподобные объекты . С настоящими массивами их роднит то, что они имеют свойство length и свойства с именами в виде чисел, соответствующие элементам массива. В качестве примеров можно назвать DOM коллекции NodeList и псевдомассив arguments , доступный внутри любой функции/метода.

1. Использование способов перебора настоящих массивов

Как минимум большинство, если не все, способы перебора настоящих массивов могут быть применены для перебора массивоподобных объектов.

Конструкции for и for...in могут быть применены к массивоподобным объектам точно тем же путем, что и к настоящим массивам.

forEach и другие методы Array.prototype также применимы к массивоподобным объектам. Для этого нужно использовать вызов Function.call или Function.apply .

Например, если вы хотите применить forEach к свойству childNodes объекта Node , то это делается так:

Array.prototype.forEach.call(node.childNodes, function(child) { // делаем что-нибудь с объектом child });

Для удобства повторного использования этого приема, можно объявить ссылку на метод Array.prototype.forEach в отдельной переменной и использовать ее как сокращение:

// (Предполагается, что весь код ниже находится в одной области видимости) var forEach = Array.prototype.forEach; // ... forEach.call(node.childNodes, function(child) { // делаем что-нибудь с объектом child });

Если в массивоподобном объекте имеется итератор, то его можно использовать явно или неявно для перебора объекта таким же способом, как и для настоящих массивов.

2. Преобразование в настоящий массив

Есть также еще один, очень простой, способ перебора массивоподобного объекта: преобразовать его в настоящий массив и использовать любой из рассмотренных выше способов перебора настоящих массивов. Для преобразования можно использовать универсальный метод Array.prototype.slice , который может быть применен к любому массивоподобному объекту. Делается это очень просто, как показано в примере ниже:

Var trueArray = Array.prototype.slice.call(arrayLikeObject, 0);

Например, если вы хотите преобразовать коллекцию NodeList в настоящий массив, вам нужен примерно такой код:

Var divs = Array.prototype.slice.call(document.querySelectorAll("div"), 0);

3. Замечание по объектам среды исполнения

Если вы применяете методы Array.prototype к объектам среды исполнения (таких как DOM коллекции), то вы должны иметь в виду, что правильная работа этих методов не гарантирована во всех средах исполнения (в т.ч. в браузерах). Это зависит от поведения конкретного объекта в конкретной среде исполнения, если точнее, от того, как в этом объекте реализована абстрактная операция HasProperty . Проблема в том, что сам стандарт ES5 допускает возможность неправильного поведения объекта по отношению к этой операции (см. §8.6.2).

Поэтому важно тестировать работу методов Array.prototype в каждой среде исполнения (браузере), в которой планируется использование вашего приложения.