Definition and Usage

The find() function for arrays returns the first element that satisfies the condition defined by a callback function.
If no element matches the condition, it returns undefined.

Here's a visual example of how it works: 
[😃, 🏀, 🍅, 🐵].find(function(item) {
    return item === 🏀;
}); // 👉 🏀

find() function is useful for finding elements in an array that match a specific condition.

Features

  • The condition is specified inside a callback function.
    - Write the callback so it returns true if the condition is met, and false otherwise.
  • Even if multiple elements match the condition, only the first matching element is returned.
  • With this behavior, the original array remains unchanged.

Basic Example

The following example demonstrates how to use the find() function to locate the first element in an array that satisfies a given condition. Each step is explained with comments.

JavaScript Finding "green" in an array using the find() function 
// Create an array
const colors = ["red", "green", "blue"];

// Find the first element that satisfies the condition
const green = colors.find(function(color) {
    return color === "green"; // check if the element is "green"
});

// Output the result
console.log(green); // Output: "green"

Syntax

JavaScript 
arr.find(callbackFn[, thisArg])

arr is the array to which the find() function is applied.

Parameters

Description of find() function parameters
callbackFn A callback function that processes each element in the array. The callback function is executed for every element and checks the condition defined within it. The condition should be defined using a return statement. If the condition evaluates to true, the element is considered found. The find() function stops iterating and returns the first element that satisfies the condition. Execution then continues after the find() call.
Callback function signature: callbackFn(element[, index[, array]])
  • element: The current element being processed
  • index: Optional. The index of the current element
  • array: Optional. The array on which find() was called
thisArg Optional. A value to use as this when executing callbackFn.

The first parameter, the callback function (callbackFn), can take various forms as follows:

JavaScript 
// Arrow function
find((element) => { /* … */ })
find((element[, index]) => { /* … */ })
find((element[, index[, array]]) => { /* … */ })

// Callback function reference
find(callbackFn)
find(callbackFn[, thisArg])

// Inline callback function
find(function (element) { /* … */ })
find(function (element[, index]) { /* … */ })
find(function (element[, index[, array]]) { /* … */ })
find(function (element[, index[, array]]) { /* … */ }[, thisArg])

Return value

The first element in the array that satisfies the condition specified by the callback function.
If no element satisfies the condition, undefined is returned.

How the Callback Function Works

JavaScript Callback function parameters 
callbackFn(element[, index[, array]])

The find() function uses a callback function written by the developer to search array elements according to the desired condition and returns the first element that satisfies the condition.

The callback function of find() checks the condition defined within it for each element in the array. The condition is specified using a return statement. If it evaluates to true, the element is considered found. The find() function stops iterating once the first matching element is found and returns that element. Execution then continues after the find() call.

JavaScript Structure of the callback function used in find() 
/**
 * Callback function
 *
 * @param {*} element Each element in the array
 * @param {number} index Optional. The index of the element
 * @param {Array} array Optional. The original array
 * @return {boolean} Returns true if the condition is met, otherwise false
 *
 * The callback function can be a named function (user-defined) or an anonymous function.
 * All callback functions can also be written as arrow functions.
 */

/* Using a named function as the callback */
function callbackFn(element[, index[, array]]) { // Named function definition
    // Define the condition using a return statement
}

arr.find(callbackFn); // Pass the defined named function directly as the argument

/* Using an anonymous function as the callback */
arr.find(function(element[, index[, array]]) {
    // Define the condition using a return statement
});

Practical Examples

The find() function is used to locate the first element in an array that satisfies a specific condition. It can be applied in various scenarios. Let's look at a few examples.

Finding a Specific Element

Use find() to locate a specific element in an array, such as a particular string or number.

JavaScript 
const numbers = [1, 2, 3, 4, 5];
const target = 3;
const found = numbers.find(element => element === target);

console.log(found); // Output: 3

Searching Based on Object Properties

Useful for finding an object in an array of objects based on a specific property value.

JavaScript 
const people = [
    {name: "Alice", age: 30},
    {name: "Bob", age: 25},
    {name: "Charlie", age: 35}
];

const targetName = "Bob";
const person = people.find(obj => obj.name === targetName);

console.log(person); // Output: {name: "Bob", age: 25}

Searching with a Custom Condition

You can create a custom condition function to search array elements based on your own criteria.

JavaScript 
const products = [
    {name: "Laptop", price: 1000},
    {name: "Phone", price: 500},
    {name: "Tablet", price: 300}
];

const customCondition = product => product.price < 600;
const affordableProduct = products.find(customCondition);

console.log(affordableProduct); // Output: {name: "Phone", price: 500}

Using the find() function allows you to efficiently locate the first element that meets a condition, making it useful in various scenarios.

Specifications

Specification for JavaScript Array find() Function
Specification
find() ECMAScript Language Specification
#sec-array.prototype.find

Browser compatibility

Browser compatibility for JavaScript Array find() Function
Method
Desktop Chrome
Chrome
DesktopDesktop Edge
Edge
Desktop Firefox
Firefox
Safari
Safari
find() 45 12 25 8

References

See also