Array.prototype.includes()

includes(searchElement, fromIndex?)

The includes() method determines whether an array includes a certain element, returning true or false as appropriate. It provides a cleaner, more readable alternative to indexOf() >= 0 for checking element existence.

Syntax

array.includes(searchElement)
array.includes(searchElement, fromIndex)

• searchElement: The value to search for in the array.
• fromIndex (optional): The position in the array to start searching from. Defaults to 0. Negative values count from the end.
• Returns: true if the element is found, false otherwise.

TypeScript Signature

interface Array<T> {
  includes(searchElement: T, fromIndex?: number): boolean;
}

Basic Examples

const fruits = ["apple", "banana", "cherry", "date"];

// Check if element exists
console.log(fruits.includes("banana"));   // true
console.log(fruits.includes("grape"));    // false

// Case-sensitive search
console.log(fruits.includes("Apple"));    // false

// Works with primitives
const numbers = [1, 2, 3, 4, 5];
console.log(numbers.includes(3));          // true
console.log(numbers.includes(10));        // false

Using fromIndex

const items = ["a", "b", "c", "b", "a"];

// Start searching from index 2
console.log(items.includes("b", 2));       // true (found at index 3)

// Start from index 4 (past the second "b")
console.log(items.includes("b", 4));       // false

// Negative fromIndex
console.log(items.includes("c", -1));      // false (searches from index 3)
console.log(items.includes("c", -2));      // true (searches from index 2)

Common Patterns

Checking Before Adding

const tags = ["javascript", "python", "rust"];

function addTag(tag) {
  if (!tags.includes(tag)) {
    tags.push(tag);
    console.log(`Added: ${tag}`);
  } else {
    console.log(`${tag} already exists`);
  }
}

addTag("go");       // Added: go
addTag("javascript"); // javascript already exists

Simple Presence Check

const allowedRoles = ["admin", "moderator", "user"];

function hasAccess(role) {
  return allowedRoles.includes(role);
}

console.log(hasAccess("admin"));      // true
console.log(hasAccess("guest"));      // false

NaN Handling

Unlike indexOf(), includes() correctly handles NaN:

const numbers = [1, NaN, 3, 4];

// indexOf fails to find NaN
console.log(numbers.indexOf(NaN));    // -1

// includes finds NaN
console.log(numbers.includes(NaN));   // true

Object Identity

includes() uses strict equality (===) for comparison. Objects are compared by reference, not value:

const users = [{ id: 1 }, { id: 2 }];
const newUser = { id: 1 };

console.log(users.includes(newUser));  // false (different reference)
console.log(users.includes(users[0])); // true (same reference)

Edge Cases

const arr = [1, 2, 3];

// Empty array search
console.log([Global_Objects::eval].includes(1));          // false

// Undefined and null
console.log([undefined, null].includes(undefined)); // true
console.log([undefined, null].includes(null));      // true

// Sparse arrays
console.log([1, , 3].includes(undefined)); // true
console.log([1, , 3].includes(2));        // false

// Start index greater than length
console.log([1, 2].includes(1, 10));      // false

Browser Compatibility

Browser	Version
Chrome	47+
Firefox	43+
Safari	9+
Edge	14+

Polyfill

Legacy environments can use this polyfill:

if (!Arrayincludes) {
  Arrayincludes = function(searchElement, fromIndex) {
    if (this == null) {
      throw new TypeError("Arrayincludes called on null or undefined");
    }
    
    const O = Object(this);
    const len = O.length >>> 0;
    
    if (len === 0) return false;
    
    const n = fromIndex | 0;
    let k = n < 0 ? Math.max(len + n, 0) : Math.min(n, len);
    
    while (k < len) {
      if (O[k] === searchElement) return true;
      k++;
    }
    
    return false;
  };
}

See Also

• array::find
• array::some