Skip to main content

filter() JavaScript Array Method – Explained with Examples

Whenever you use filter() on an array, the method does the following:

  1. It creates a new array.
  2. It populates the newly created array with all the calling array's elements that passed the test specified by filter's function argument.
note
  • Any function you provide as filter()'s argument will get called on each item in the calling array.
  • A calling array is an array on which you used filter(). So, in bestColorsList.filter(func), bestColorsList is the calling array.
  • filter() is sometimes written as Array.prototype.filter() because it is a method of the Array object's prototype property.

Suppose none of the calling array's items passed the function argument's test. In that case, filter() will create and return only an empty array.

Syntax of the filter() Method​

filter() accepts two arguments: a "callback function" and a "thisValue." Here is the syntax:

callingArray.filter(callback, thisValue);

Argument 1: callback​

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

The callback function returns the Boolean true (or false).

In other words, the callback returns true whenever an element of the calling array passes the specified test. In that case, filter() will duplicate the item into the newly created array.

But the callback will return false whenever an item fails the specified test. In that case, filter() will not copy the failed item into the newly created array.

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

callingArray.filter((currentItem, index, array) => {
  // Test to run on each item of the calling array
});
note

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

Parameter 1: currentItem​

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

Parameter 2: index​

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

Parameter 3: array​

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

note
  • You can rename the currentItem, index, and array parameters to anything you prefer.
  • The computer will invoke filter()'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.
  • filter() does not change the original array. (Although you can do so with the callback argument.)

Argument 2: thisValue​

A thisValue is the second argument accepted by the filter() method. It is an optional argument representing the value you want to use as the function argument's this value.

callingArray.filter((currentItem, index, array) => {}, thisValue);

Suppose you do not provide a second argument. In that case, the computer will use undefined as the callback function's this value.

Example 1: How to Use filter() without a thisValue Argument​

Here is an example of the filter() method without a thisValue argument:

const colors = ["red", "blue", "green", "white", "yellow", "pink"];

function eachValue(currentItem) {
  return currentItem.length > 4;
}

const newArray = colors.filter(eachValue);
console.log(newArray);

// The console.log invocation above will return:
["green", "white", "yellow"];

Try it on StackBlitz

In the snippet above, we used the filter() method to filter out the colors array's items having lengths greater than four (4).

Therefore, the computer will create a new array and populate it with the values that passed the test of having lengths greater than four (4).

note

The colors array is the calling array in the example above.

Example 2: How to Use filter() with a thisValue Argument​

Here is an example of the filter() method with a thisValue argument:

const colors = ["red", "blue", "green", "white", "yellow", "pink"];

function eachValue(currentItem, ind, arr) {
  arr[ind + 1] += this;
  return currentItem.length > 4;
}

const newArray = colors.filter(eachValue, "Car");
console.log(newArray);

// The console.log invocation above will return:
["blueCar", "greenCar", "whiteCar", "yellowCar", "pinkCar"];

Try it on StackBlitz

In the snippet above, we used the filter() method to filter out the colors array's items having lengths greater than four (4).

Observe that we used the eachValue callback function to add filter()'s this value to each of the colors array's items—except the first one.

In other words, we used the callback function to mutate the original array.

Therefore, colors' current content will be:

[
  "red",
  "blueCar",
  "greenCar",
  "whiteCar",
  "yellowCar",
  "pinkCar",
  "undefinedCar",
];
tip
  • Use every() if you only need to return true or false when all the calling array's items pass or fail the specified test.
  • Suppose you only need to return the item that first passed the specified test. In that case use find().
  • Use findIndex() if you need to return only the index of the first item that passed the specified test.

Overview​

filter() creates a new array that contains all the calling array's elements that passed the test specified by the method's function argument.