The JavaScript Array includes() method checks whether an array contains a specified value (either a primitive or a reference type) among its elements. It returns a boolean value: true if the value is found, and false otherwise.

The primary purpose of an array.includes() method is to check the element’s existence in the array, and uses SameValueZero (like === but treats NaN as equal and -0 equal to +0) equality algorithm. It abstracts away the need to manually iterate or use index-based checks, which is a time-consuming process.

In the above figure, the “Bill” element is included in the array, which is why it returns true. 

const nm = ["Elon", "Zuck", "Jeff", "Bill", "Page"];

console.log(nm.includes("Bill"));

// Output: true

Syntax

array.includes(search_element, fromIndex)

Parameters

Argument	Description
search_element (required)	It represents a value to search in the input array. It can be of any type, including numbers, strings, objects, arrays, undefined, null, or NaN.
fromIndex (optional)	It is an integer representing the index at which to start the search in the array. By default, the index is 0.

Using the “fromIndex” argument

The “fromIndex” is a valuable argument that defines the starting point for the search in the array. It enables partial array scans. Negative values are offset from the end.

let nm = ["Elon", "Zuck", 'Jeff', 'Bill', 'Page'];

console.log(nm.includes("Jeff", 1));

// Output: true

// Passing negative index

console.log(nm.includes("Zuck", -2));

// Output: false

In the first case, we passed two arguments. It returns true because the value “Jeff” is present in the array nm, starting from index 1, and “Jeff” is located at index 2.

In the second case, we passed two arguments, the second argument being a negative index.

Due to a negative index of -2, it starts searching from the element “Bill”  and searches for the “Zuck” element. Since the “Zuck” element is not there, it returns false.

Element does not exist

What if the element you are trying to search for in the array does not exist? In that case, it returns False.

const nm = ["Elon", "Zuck", "Jeff", "Bill", "Page"];

console.log(nm.includes("Buffett"));

// Output: false

Case-sensitive search

When you attempt to compare strings, the includes() function is case-sensitive. Strings are compared strictly, including case. For case-insensitive checks, use some() with the toLowerCase() method.

let nm = ["Elon", "Zuck", "Jeff", "Bill", "Page"];

console.log(nm.includes("page"));

// Output: false

console.log(nm.includes("Page"));

// Output: true

Searching for Objects (Reference Equality)

The includes() method checks Objects by reference, not deep equality.

For content-based search, use some() or JSON.stringify() methods (with caveats for order/circular refs).

const obj1 = { name: "Steve" };
const obj2 = { name: "Steve" };

const objects = [obj1];

console.log(objects.includes(obj1));

// Output: true (same reference)

console.log(objects.includes(obj2));

// Output: false (different reference)

In the above code, obj1 and obj2 both have the same structure and properties, but they live at different memory addresses. Let’s say obj1’s memory address is A and obj2’s memory address is B.

The includes() uses SameValueZero comparison, which for objects means checking if they are literally the same reference.

The objects = [ obj1 ] only contain reference A, so searching for B fails. That’s is why for obj1, it returns true and for obj2, it returns false.

Searching for Arrays (Reference Equality)

Like Objects, Arrays are compared by reference too!. This is common in nested data structures.

const arr1 = [1, 2];
const arr2 = [1, 2];

const nested = [arr1];

console.log(nested.includes(arr1));

// Output: true

console.log(nested.includes(arr2));

// Output: false

Here, the logic is the same as we used in the above Objects section.

Both arrays, arr1 and arr2, have different memory addresses even though they contain the same values.

NaN, undefined, and null

The includes() method correctly identifies NaN, making it preferable over indexOf() for arrays that may contain NaN.

The includes() method correctly distinguishes between null, undefined, and an empty string. 

const falsy_values = [1, NaN, 3, undefined, null, ''];

console.log(falsy_values.includes(NaN));

// Output: true

console.log(falsy_values.includes(undefined));

// Output: true

console.log(falsy_values.includes(null));

// Output: true

console.log(falsy_values.includes(''));

// Output: true (strict match)

console.log(falsy_values.includes());

// Output: true

As you can see, it correctly identifies all types of falsy values.

That’s all!