includes()

The JavaScript includes() method will check if an array includes a certain value, returning true or false.

Syntax

const result = array.includes(valueToFind, fromIndex);

Parameters:

• valueToFind: The value to search for from the array.
• fromIndex (optional): The index to begin searching the array, defaulting to 0. If fromIndex is greater than or equal to the array length, false is returned and the array is not searched. If fromIndex is negative, it searches from the end of the array.

Basic usage

Let's check if our pizza toppings array contains certain items:

const pizzaToppings = ['Cheese', 'Pepperoni', 'Mushrooms', 'Olives', 'Anchovies'];

// Check if 'Anchovies' are included
const hasAnchovies = pizzaToppings.includes('Anchovies');
console.log("Includes Anchovies?", hasAnchovies);
// Output: Includes Anchovies? true

// Check if 'Pineapple' is included
const hasPineapple = pizzaToppings.includes('Pineapple');
console.log("Includes Pineapple?", hasPineapple);
// Output: Includes Pineapple? false

The includes() method performs a case-sensitive search:

const pizzaToppings = ['Cheese', 'Pepperoni', 'Mushrooms'];

const hasCheeseLowercase = pizzaToppings.includes('cheese'); // lowercase 'c'
console.log("Includes 'cheese' (lowercase)?", hasCheeseLowercase);
// Output: Includes 'cheese' (lowercase)? false

Using the fromIndex parameter

You can specify where the search should start. The following example looks for Pepperoni, starting from different index positions:

const pizzaToppings = ['Cheese', 'Pepperoni', 'Mushrooms', 'Pepperoni', 'Olives', 'Pineapple'];

// Check for 'Pepperoni' in the full array (default)
const includesPepperoni = pizzaToppings.includes('Pepperoni');
console.log("Includes 'Pepperoni' from start?", includesPepperoni);
// Output: Includes 'Pepperoni' from start? true (finds it at index 1)

// Check for 'Pepperoni' starting from index position 2
const includesPepperoniFromIndex2 = pizzaToppings.includes('Pepperoni', 2);
console.log("Includes 'Pepperoni' from index position 2?", includesPepperoniFromIndex2);
// Output: Includes 'Pepperoni' from index 2? true (finds it at index 3)

// Check for 'Pepperoni' starting from index position 4
const includesPepperoniFromIndex4 = pizzaToppings.includes('Pepperoni', 5);
console.log("Includes 'Pepperoni' from index 4?", includesPepperoniFromIndex4);
// Output: Includes 'Pepperoni' from index position 4? false (starts at 'Pineapple')

Using a negative fromIndex number will count from the end of the array:

const pizzaToppings = ['Cheese', 'Pepperoni', 'Mushrooms', 'Olives'];

// Check for 'Mushrooms' starting from the last 2 elements (index -2 => 4 + (-2) = 2)
const mushroomsFromEnd = pizzaToppings.includes('Mushrooms', -2);
console.log("Includes 'Mushrooms' in last 2?", mushroomsFromEnd);
// Output: Includes 'Mushrooms' in last 2? true (starts search at 'Mushrooms')

// Check for 'Cheese' starting from the last 2 elements
const cheeseFromEnd = pizzaToppings.includes('Cheese', -2);
console.log("Includes 'Cheese' in last 2?", cheeseFromEnd);
// Output: Includes 'Cheese' in last 2? false (starts search at 'Mushrooms')

Handling NaN

An advantage of includes() over indexOf() is it's ability to find NaN:

const values = [1, 5, NaN, 10];

// Using indexOf() to find NaN
const indexOfNaN = values.indexOf(NaN);
console.log("Using indexOf():", indexOfNaN);
// Output:"Using indexOf():" -1  (indexOf cannot find NaN)

// Using includes() to find NaN
const includesNaN = values.includes(NaN);
console.log("Using includes():", includesNaN);
// Output: "Using includes():" true

Working with objects in arrays

The includes() method checks for equality using strict comparison (===). It does not look inside objects to find if an object with certain properties exists. It only checks if the exact same object reference is in the array.

const pizzaMenu = [
  { name: 'Margherita', price: 10 },
  { name: 'Pepperoni', price: 12 }
];

const margheritaPizza = pizzaMenu[0]; // Reference to the first object
const anotherMargherita = { name: 'Margherita', price: 10 }; // Different object instance

// Check if the exact first object is included
const includesExactMargherita = pizzaMenu.includes(margheritaPizza);
console.log("Includes the exact Margherita object?", includesExactMargherita);
// Output: Includes the exact Margherita object? true

// Check if an object with the same properties is included
const includesSimilarMargherita = pizzaMenu.includes(anotherMargherita);
console.log("Includes a similar Margherita object?", includesSimilarMargherita);
// Output: Includes a similar Margherita object? false (it's a different object reference)

// To check if an object with certain properties exists, use find() or some()
const hasMargheritaName = pizzaMenu.some(pizza => pizza.name === 'Margherita');
console.log("Includes a pizza named Margherita?", hasMargheritaName);
// Output: Includes a pizza named Margherita (using some())? true

When to use includes() vs. other methods

Use includes() when:

• You want to know if NaN is in an array.
• You want a Boolean true or false result.
• The index of the found element is not needed.
• You want to know if a specific primitive value (string, number, boolean, null, undefined, symbol, bigint) in in the array.

Consider using other methods when:

• You need the index of the first occurrence of a value (use indexOf() or findIndex()). Note: indexOf() cannot find NaN.
• You need to check if an element satisfying a specific condition exists (use some()). This is needed for checking object properties.
• You need to check if all elements meet a condition (use every()).
• You need to find the first element that meets a condition (use find()).
• You need a new array containing elements that match a condition (use filter()).

Conclusion

The includes() method offers a way to check if an array contains a certain value, returning a boolean value of true or false. Its can find NaN which gives it an advantage over indexOf(). Since it uses strict comparison it won't find objects based on property values alone, use some() or find() if required.