Skip to main content

reduce() JavaScript Array Method – Explained with Examples

Whenever you use reduce() on an array, the method uses its function argument to reduce its calling array's items to a single value.

note
  • Any function you provide as reduce()'s argument will get called on each item in the calling array.
  • A calling array is an array on which you used reduce(). So, in bestColorsList.reduce(func), bestColorsList is the calling array.
  • reduce() is sometimes written as Array.prototype.reduce() because it is a method of the Array object's prototype property.

Here's an example:

const numbers = [1, 2, 3, 4];

numbers.reduce(function (accumulator, currentItem) {
  return accumulator + currentItem;
});

// The invocation above will return: 10

Try it on StackBlitz

In the snippet above, we used the reduce() method to sum up all the values inside the numbers array. Thereby reducing the calling array's content to a single value—that is, 10.

The reduce() method does its reduction by executing its function argument once for each item of the calling array.

The value returned after each execution gets stored in the function's accumulator parameter.

Here's another example:

const numbers = [56, 1, 2, 3];

numbers.reduce(function (accumulator, currentItem) {
  return accumulator - currentItem;
});

// The invocation above will return: 50

Try it on StackBlitz

The snippet above used the reduce() method to deduct all the values inside the numbers array. Thereby reducing the calling array's content to a single value—that is, 50.

Syntax of the reduce() Method​

reduce() accepts two arguments. Here is the syntax:

array.reduce(callback, initialValue);

Argument 1: callback​

A function is the first argument accepted by the reduce() method. It is a required argument containing the code you want the computer to invoke for each item of the calling array.

Keep in mind that reduce()'s function argument accepts four parameters: accumulator, currentItem, index, and an array.

array.reduce((accumulator, currentItem, index, array) => {
  // Code to run for each item of the calling array
});
note

() => {...} is an arrow function shorthand for function () {...}.

Parameter 1: accumulator​

The accumulator parameter is required. It accumulates the values returned each time the computer invokes the callback argument on each item of the calling array.

Parameter 2: currentItem​

The currentItem parameter is required. It represents the current calling array's item the computer is currently processing.

Parameter 3: index​

The index parameter is optional. It represents the index number of the item the computer is currently processing.

Parameter 4: array​

The array parameter is also optional. It represents the calling array.

note
  • You can rename the accumulator, currentItem, index, and array parameters to anything you prefer.
  • The computer will invoke reduce()'s function argument only once for each item inside the calling array. The invocation will be in the order of the array items from left to right.
  • reduce() does not change the original array. (Although you can do so with the callback argument.)

Argument 2: initialValue​

An initialValue is the second argument accepted by the reduce() method. It is an optional argument representing the first value you want to use as the accumulator parameter's initial value.

callingArray.reduce(function (accumulator, currentItem, index, array) {},
initialValue);

Suppose you omit the initialValue argument. In that case, reduce() will use the calling array's first value as the accumulator parameter's initial value. And the array's second value will get used as the currentItem parameter's first value.

note

It is always better to provide an initialValue—even if that value is 0. By so doing, you will avoid unexpected results.

reduce() with an initialValue vs. reduce() without an initialValue​

Whenever you provide an initialValue argument, the index counting will begin from the calling array's first item.

Here's an example:

const numbers = [10, 20, 30, 40];

numbers.reduce(function (accumulator, currentItem, index) {
  console.log(`The current item (${currentItem}) is on index ${index}`);
  return accumulator + currentItem;
}, 500);

// The invocation above will return:
// "The current item (10) is on index 0"
// "The current item (20) is on index 1"
// "The current item (30) is on index 2"
// "The current item (40) is on index 3"
// 600

Try it on StackBlitz

Whenever you omit the initialValue argument, the index counting will begin from the calling array's second item.

The index counting will start from the calling array's second value because reduce() will use the first item as the initial accumulator parameter.

Here's an example:

const numbers = [10, 20, 30, 40];

numbers.reduce(function (accumulator, currentItem, index) {
  console.log(`The current item (${currentItem}) is on index ${index}`);
  return accumulator + currentItem;
});

// The invocation above will return:
// "The current item (20) is on index 1"
// "The current item (30) is on index 2"
// "The current item (40) is on index 3"
// 100

Try it on StackBlitz

Note that the reduce() method is not only for addition and subtraction. For instance, you can use it to flatten nested arrays.

Here's an example:

const nestedArrays = [
  [20, 30],
  ["Code", "Sweetly"],
  [true, "Grace"],
];

nestedArrays.reduce(function (accumulator, currentItem) {
  return [...accumulator, ...currentItem];
}, []);

// The invocation above will return:
[20, 30, "Code", "Sweetly", true, "Grace"];

Try it on StackBlitz

The snippet above used the spread operator (...) to expand the accumulator and the currentItem parameters into a new array.

In other words, each time reduce()'s callback gets executed on the nested arrays, the spread operator will expand the accumulator and the currentItem's content into the new array.

Overview​

reduce() uses its function argument to reduce its calling array's items to a single value.