es-toolkit/docs/reference/compat/array/findIndex.md

findIndex

::: info This function is only available in es-toolkit/compat for compatibility reasons. It either has alternative native JavaScript APIs or isn’t fully optimized yet.

When imported from es-toolkit/compat, it behaves exactly like lodash and provides the same functionalities, as detailed here. :::

Returns the index of the first item in an array that meets the specified condition.

You can specify the condition in several ways:

• Predicate function: If you provide a predicate function, the function will be applied to each item. The first item that makes the predicate function return true will be selected.
• Partial object: If you provide a partial object, the function will return the first item that matches the properties of the partial object.
• Property-value pair: If you provide a property-value pair, the function will return the first item that matches the property and value from the pair.
• Property name: If you provide a property name, the function will return the first item where the specified property has a truthy value.

Signature

function findIndex<T>(arr: T[], doesMatch: (item: T, index: number, arr: T[]) => unknown): number;
function findIndex<T>(arr: T[], doesMatch: Partial<T>): number;
function findIndex<T>(arr: T[], doesMatch: [keyof T, unknown]): number;
function findIndex<T>(arr: T[], doesMatch: string): number;

Parameters

• arr (T[]): The array to search through.

• doesMatch:

  • Predicate function ((item: T, index: number, arr: readonly T[]) => unknown): A function that takes an item, its index, and the array, and returns a truthy value if the item matches the criteria.
  • Partial object (Partial<T>): A partial object that specifies the properties to match.
  • Property-value pair ([keyof T, unknown]): An array where the first element is the property key and the second element is the value to match.
  • Property name (string): The name of the property to check for a truthy value.

Returns

(number): The index of the first item that has the specified property value, or -1 if no match is found.

Examples

import { findIndex } from 'es-toolkit/compat';

// Using a predicate function
const items = [1, 2, 3, 4, 5];
const result = findIndex(items, item => item > 3);
console.log(result); // 3

// Using a partial object
const items = [
  { id: 1, name: 'Alice' },
  { id: 2, name: 'Bob' },
];
const result = findIndex(items, { name: 'Bob' });
console.log(result); // 1

// Using a property-value pair
const items = [
  { id: 1, name: 'Alice' },
  { id: 2, name: 'Bob' },
];
const result = findIndex(items, ['name', 'Alice']);
console.log(result); // 0

// Using a property name
const items = [
  { id: 1, name: 'Alice' },
  { id: 2, name: 'Bob' },
];
const result = findIndex(items, 'name');
console.log(result); // 0