Array.prototype.find()
Returns the first element that satisfies the test, or undefined if none does.
find(callbackFn)
find(callbackFn, thisArg)- Added in JavaScript ES2015
Parameters
| Parameter | Type | Description |
|---|---|---|
$callbackFn | Function | Function run for each element, called with (element, index, array). Return a truthy value to signal a match. |
$thisArgoptional | any= undefined | Value to use as this when executing callbackFn. Ignored by arrow functions. |
Return value
any | undefinedThe first element for which callbackFn returned a truthy value, or undefined if no element matched.
Errors
Nothing of its own — errors thrown by callbackFn propagate and stop the search.
find() scans from index 0 and returns the element itself the moment the callback returns something truthy. It stops there, so on a large array with an early match it does far less work than filter(). Use it whenever you expect exactly one hit — looking a record up by id is the canonical case.
find() or includes() or indexOf()?
If you are testing membership of a primitive, includes() is shorter and clearer. find() earns its place when the match is a predicate over object fields rather than an equality check.
What trips people up
A miss returns undefined, so the very next property access throws TypeError: Cannot read properties of undefined. Guard it, or use optional chaining: users.find(u => u.id === id)?.name.
undefined is also a legitimate element value, so a returned undefined cannot tell you whether the array held one or nothing matched. When that distinction matters, use findIndex() and compare against -1.
Unlike map() and filter(), find() visits holes in sparse arrays and treats them as undefined.
Example
When to use it
- Look a user or record up by id in an in-memory list
- Find the first configuration entry whose key matches
- Locate the first item in a queue that is still pending
- Grab the first element over a threshold without scanning the rest
Frequently asked questions
What does find() return when nothing matches?
undefined. Because undefined can also be a real element, use findIndex() and check for -1 when you need to distinguish 'found an undefined' from 'found nothing'.
Is find() faster than filter()?
Yes when a match exists, because find() stops at the first hit while filter() always walks the whole array and allocates a result array. With no match both scan everything.
Can find() search an array of objects by a nested property?
Yes — the callback is arbitrary code, so users.find(u => u.address?.city === 'Oslo') works. Use optional chaining inside the predicate so a missing intermediate object does not throw.
More examples
undefined is ambiguous
The first and third lines both print undefined, yet only the first one actually matched something. findIndex prints 1 on line two, which is how you tell a real undefined element apart from 'nothing found'.
const values = [0, undefined, 5];
console.log(values.find((v) => v === undefined));
console.log(values.findIndex((v) => v === undefined));
console.log([1, 2, 3].find((v) => v === undefined));The returned element is live
Prints 'light' and true. find() hands back the same object reference stored in the array, so assigning to it edits the array in place. Spread it into a new object first if you want an isolated copy.
const config = [
{ key: "theme", value: "dark" },
{ key: "lang", value: "en" },
];
const entry = config.find((e) => e.key === "theme");
entry.value = "light";
console.log(config[0].value);
console.log(entry === config[0]);
Discussion