Skip to main content

find() Method – How to Find the Element that First Passes a Test

Whenever you use find() on an array, the method returns the calling array's value that first passes the function argument's test.

But if no element passes the test, find() will return undefined.

note
  • find() does not alter the original array.
  • A calling array is an array on which you used find(). So, in bestColorsList.find(func), bestColorsList is the calling array.
  • find() is sometimes written as Array.prototype.find() because it is a method of the Array object's prototype property.

Syntax of the find() Method​

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

callingArray.find(callback, thisValue);

Argument 1: callback​

A function is the first argument accepted by the find() 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 value that first passed the test or undefined if it finds no item.

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

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

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

Buy CSS Grid book

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 find()'s function argument once for each item inside the calling array until it finds a truthy value. Once find() discovers a truthy element, it will immediately return the item's value. The invocation will be in the order of the array items from left to right.
  • find() 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 find() method. It is an optional argument representing the value you want to use as the function argument's this value.

callingArray.find((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 find() without a thisValue Argument​

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

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

function itemLength(currentItem) {
  return currentItem.length > 3;
}

const firstValueFound = colors.find(itemLength);
console.log(firstValueFound);

// The console.log invocation above will return: "blue"

Try it on StackBlitz

The snippet above used the find() method to find the first color having lengths greater than three (3).

note

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

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

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

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

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

const firstValueFound = colors.find(itemLength, "Car");
console.log(firstValueFound);

// The console.log invocation above will return: "blueCar"

Try it on StackBlitz

In the snippet above, we used the find() method to find the first color having lengths greater than three (3).

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

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

Therefore, the colors array's current content will be:

["red", "blueCar", "greenCar", "white", "yellow", "pink"]
tip
  • Use filter() if you need to return all the items that passed the specified test.
  • Use findIndex() if you need to return only the index of the first item that passed the specified test.

Overview​

find() finds the calling array's element that first passes the test specified by the method's function argument.