JavaScript Array.includes() Method

JavaScript’s Array object provides methods for working with collections of values. Use includes() to check whether an array contains a particular value. It returns true when it finds a match and false otherwise, so it is useful in conditions as well as direct checks.

What includes() checks

includes() searches an array for a value using the SameValueZero comparison. For ordinary values, this behaves much like strict equality; notably, NaN matches NaN. Objects match only when the array contains the same object reference, not a separate object with identical properties. String comparisons are case-sensitive, so 'Shark' and 'shark' are different values.

The method does not change the array. It answers whether the value occurs in the portion being searched and returns a Boolean result.

Syntax

Call the method on the array instance as array.includes(searchElement, fromIndex).

The fromIndex argument is optional. If omitted, searching begins at index 0.

Parameters and return value

searchElement is the value to look for. It may be a number, string, object, or another value stored in the array. fromIndex is the zero-based index where the search begins. The method returns true if a matching element is found at or after that position, and false if no such element is found.

Because the result is Boolean, use it directly in a conditional, such as if (allowedNames.includes(name)). There is no need to compare the result with true.

Search behavior and limitations

The starting index changes which portion of the array is examined. For example, if the sought value is at index 2, starting at index 1 can find it, while starting at index 3 skips it. A negative fromIndex counts back from the end: -1 starts at the last element, and a value whose magnitude is at least the array length starts at index 0. If the calculated start is beyond the final index, the search returns false.

The search is forward from its starting position; it does not wrap around to earlier elements. For an empty array, or when no matching value occurs in the searched portion, the result is false. If case-insensitive string matching is needed, normalize both the stored strings and the search value consistently before checking.

Examples

The arrays below hold numbers and animal names. Each call prints whether the requested value occurs in the searched portion. The first pair shows a present and an absent number. The next pair uses names with matching and differing letter case. The last pair starts the search at two different positions to show how the optional index changes the result. Run this example:

const numbers = [1, 3, 5, 7, 9];
const animals = ['Whale', 'Dolphin', 'Eel', 'Shark'];

console.log(numbers.includes(5));
console.log(numbers.includes(50));
console.log(animals.includes('Shark'));
console.log(animals.includes('shark'));
console.log(numbers.includes(5, 1));
console.log(numbers.includes(5, 3));

true
false
true
false
true
false

Use the Boolean result to branch on whether a value was found. The final two checks demonstrate that beginning before index 2 includes the 5, while beginning at index 3 searches only later positions.