findIndex() is find()'s counterpart when you need the position of a match rather than the element itself — essential for follow-up operations like splicing or replacing an item immutably.
1Array.prototype.findIndex() | JavaScript Tutorial - In-Depth Guide Part 1
findIndex() returns the index of the first element satisfying the callback, or -1 if none match.
const index = users.findIndex((u) => u.id === targetId);Finding a Position
2Array.prototype.findIndex() | JavaScript Tutorial - In-Depth Guide Part 2
-1 is the 'not found' sentinel for findIndex(), matching the long-standing convention used by indexOf() and lastIndexOf().
const index = users.findIndex((u) => u.id === 'missing');
index; // -1The -1 Sentinel
3Array.prototype.findIndex() | JavaScript Tutorial - In-Depth Guide Part 3
findIndex() differs from indexOf() by accepting a callback predicate instead of a value to match with strict equality.
const i1 = [10, 20, 30].indexOf(20); // 1
const i2 = users.findIndex((u) => u.email === 'a@b.com'); // condition-basedfindIndex() vs indexOf()
4Array.prototype.findIndex() | JavaScript Tutorial - In-Depth Guide Part 4
findIndex() is the standard first step for immutably replacing or removing an item at a matched position without mutating the original array.
function replaceAt(arr, index, newItem) {
return [...arr.slice(0, index), newItem, ...arr.slice(index + 1)];
}
replaceAt(users, users.findIndex(u => u.id === id), updatedUser);Immutable Replace Pattern
5Array.prototype.findIndex() | JavaScript Tutorial - In-Depth Guide Part 5
Always check for -1 before using a findIndex() result as an array index, to avoid silently mutating or reading the wrong element.
const index = arr.findIndex(matcher);
if (index === -1) {
throw new Error('Item not found');
}
arr.splice(index, 1);Always Guard -1
6Step-by-Step Breakdown
findIndex() returns the index of the first element satisfying the callback, or -1 if none match.
-1 is the 'not found' sentinel for findIndex(), matching the long-standing convention used by indexOf() and lastIndexOf().
Checkpoint: What does findIndex() return when no element matches?
- →-1
- →undefined, just like find()
findIndex() differs from indexOf() by accepting a callback predicate instead of a value to match with strict equality.
Checkpoint: Can findIndex() search using a custom condition, like matching an object by a property value?
- →Yes, its callback can express any condition
- →No, it only checks strict equality like indexOf()
findIndex() is the standard first step for immutably replacing or removing an item at a matched position without mutating the original array.
Always check for -1 before using a findIndex() result as an array index, to avoid silently mutating or reading the wrong element.
Next, we'll explore 'The flat() Method'.
Level Up 🚀
Advanced cheat sheets, SEO tricks, and interview prep for this topic.
Browser Support
Fully supported.
Fully supported.
Fully supported.
Fully supported.
Accessibility (A11y)
1Announce a Clear Message When findIndex() Returns -1 in a Search Feature
If a keyboard-navigable list uses findIndex() to jump to a matching item as the user types, explicitly handle the -1 case with a spoken 'no match found' announcement instead of leaving focus in an undefined state.
SEO Implications
- 1
No Direct SEO Effect
findIndex() is a positional lookup utility with no direct SEO relevance beyond general code correctness.
Best Practices
Always Guard Against -1 Before Using the Result as an Index
Passing -1 into slice/splice silently produces a technically valid but semantically wrong result instead of an obvious error, so an explicit check catches the "not found" case loudly.
Use findIndex() (Not indexOf()) When Matching by a Property or Custom Condition
indexOf() only supports strict equality against a fixed value; any condition-based search over objects requires findIndex()'s callback.
Frequent Bugs
Passing an unguarded -1 result from findIndex() directly into splice(), which interprets -1 as counting from the end of the array and deletes the wrong element.
Explicitly check `if (index === -1)` and handle the not-found case before using the index in any array operation.
Using indexOf() to search an array of objects by a property value, which always returns -1 because indexOf() compares by strict reference/value equality, not by property.
Switch to findIndex() with a callback that checks the specific property, e.g. `arr.findIndex(u => u.id === id)`.
Real-World Examples
Immutably Updating One Item in a List
A todo-list app needed to toggle the completed status of a single item by ID, without mutating the array held in application state.
function toggleComplete(todos, id) {
const index = todos.findIndex((t) => t.id === id);
if (index === -1) return todos;
const updated = { ...todos[index], completed: !todos[index].completed };
return [...todos.slice(0, index), updated, ...todos.slice(index + 1)];
}