The JavaScript Array indexOf() vs. includes() Methods

The JavaScript Array indexOf() and includes() methods determine whether or not an array contains a specified element. indexOf() returns a numeric value denoting the location of the value's position in the array, while includes() returns a boolean value, true if the array contains the element, and false if the array does not contain the element.

The Old Way of Searching for Array Elements

In the older days of web development, searching for an array was possible, but a little less standardized and a little more confusing.

Instead of a method that returned true or false, you could return the element's position in an array using the indexOf() method:

var fruits = ["Apples", "Bananas", "Mangos", "Oranges"];

console.log(fruits.indexOf("Oranges"));
// 3

That doesn't seem too bad, right?  It's not, really.  However, a little harder to read and more difficult to work with.  If the element were found, the position of that element within the array would be returned rather than a simple boolean value.  In this example, 3 is returned because Oranges exists in the third array position.

If the element does not exist in the array, it would look like this:

var fruits = ["Apples", "Bananas", "Mangos", "Oranges"];

console.log(fruits.indexOf("Kiwis"));
// -1

And, to check for non-existence of this value in the array, you would need to do this:

if (fruits.indexOf("Kiwis") === -1) {
console.log("Kiwis not found.");
}

It gets the job done, but isn't as straightforward.

The includes() Method Explained

ECMAScript 2016 standardized this functionality by providing the Array.prototype.includes() method, returning a boolean value rather than a numeric value.

The includes() method is defined as follows:

array.includes(element, start)
  • The element parameter is required, and is the element, or value, that will be searched throughout each array node, or position.
  • The start parameter is optional, with a default value of 0, the first value within an array. This is the position in the array where the search will begin.

A Few includes() Method Examples

Here are some quick examples to help you fully understand the logic behind the includes() method:

var fruits = ["Apples", "Bananas", "Mangos", "Oranges"];

console.log(fruits.includes("Oranges"));
// true

Here, we're creating an array with four elements, each element containing a type of fruit. We're then outputting the result to the console. The output in this example is true because the string Oranges exists in the fruits array.

When searching for an element that does not exist in the array, the result will return false:

console.log(fruits.includes("Pears"));
// false

What Happens When the start Value Is Less Than Zero

If the start value is negative, the computed index is calculated by adding the array length to the specified start value. Here's an example:

var array = ["a", "b", "c"];

array.includes("a", -10); // true
array.includes("b", -10); // true
array.includes("c", -10); // true
array.includes("a", -2); // false

In this example, the array length is 3. And, for the first three includes() checks, the start value is -10:

3 + (-10) = -7

Meaning the actual start value is -7, which is smaller than the length of the array. Here, true is returned since the includes() method is able to search the entire array.

On the last line, the array length is still 3, but the start value is -2:

3 + (-2) = 1

Now we're starting at array position 1, where b is located, and searching through to the end of the array. Since a is at position 0 of the array, the element is not found and the method returns false.

Other Useful Tidbits

  • Comparison strings and characters processed by the includes() method are always case-sensitive. This means if the array contains the string Oranges but we're searching for text oranges, the result will be false because the case is different between both occurrences of the word.
  • The includes() method uses the sameValueZero() operation to determine whether or not the given element is found within the array.
The sameValueZero() operation accepts two parameters, x and y, and compares those two values returning true if the values match, and false if the values do not match, similar to the includes() method.

Browser Support

The JavaScript Array includes() method is supported by all modern browsers and versions. The only exceptions at the time of this writing are all versions of Internet Explorer and Opera, which are not supported.

You can view all supported browsers and versions by clicking the button below:

Browser Support

Conclusion

The JavaScript Array includes() method provides a clean, ease to use solution for searching for specific elements within arrays by returning a boolean value rather than numeric values that must be calculated.

It doesn't mean you need to leave indexOf() in the dust.  This is a great method for finding the array index, or position, of a specific value and can also be useful in certain scenarios.