Mastering JavaScript’s `Array.includes()` Method: A Beginner’s Guide to Data Existence

Written by

javascriptfundamentals

in

In the world of JavaScript, we frequently work with collections of data, often stored in arrays. Imagine you’re building an e-commerce website, and you need to check if a product ID exists in a user’s shopping cart. Or perhaps you’re developing a game and need to determine if a specific score is already present in a leaderboard. These scenarios, and countless others, require a fundamental ability: checking if an array contains a particular value. This is where the `Array.includes()` method comes into play. This guide will walk you through everything you need to know about `Array.includes()`, from its basic usage to more advanced applications, ensuring you can confidently determine data existence in your JavaScript projects.

What is `Array.includes()`?

The `Array.includes()` method is a built-in JavaScript function designed to determine whether an array contains a specified value. It simplifies the process of checking for the presence of an element within an array, returning a boolean value (`true` or `false`) to indicate the result.

Here’s the basic syntax:

array.includes(searchElement, fromIndex)
  • searchElement: This is the value you’re looking for within the array.
  • fromIndex (optional): This parameter specifies the index of the array at which to start searching. If omitted, the search starts from the beginning of the array (index 0).

The method returns:

  • true: If the searchElement is found in the array.
  • false: If the searchElement is not found in the array.

Basic Usage of `Array.includes()`

Let’s start with some simple examples to illustrate how `Array.includes()` works. Consider an array of fruits:

const fruits = ['apple', 'banana', 'orange', 'grape'];

Now, let’s check if the array includes ‘banana’:

console.log(fruits.includes('banana')); // Output: true

And let’s check if it includes ‘kiwi’:

console.log(fruits.includes('kiwi')); // Output: false

As you can see, the method directly returns a boolean value, making it easy to use in conditional statements.

Using `fromIndex`

The optional fromIndex parameter allows you to specify the starting position for the search. This can be useful if you only want to check a portion of the array. Let’s revisit our fruits example:

const fruits = ['apple', 'banana', 'orange', 'grape'];

If we want to check if ‘orange’ is present, starting the search from index 2:

console.log(fruits.includes('orange', 2)); // Output: true

If we started from index 3:

console.log(fruits.includes('orange', 3)); // Output: false

In the second example, even though ‘orange’ exists, the search starts at index 3, which is ‘grape’, and thus ‘orange’ is not found.

`Array.includes()` and Data Types

`Array.includes()` is case-sensitive and considers data types when comparing values. Let’s see how this works with numbers and strings:

const numbers = [1, 2, 3, 4, 5];

console.log(numbers.includes(3)); // Output: true (number)
console.log(numbers.includes('3')); // Output: false (string)

In this example, even though ‘3’ looks like a number, it’s a string, and `Array.includes()` correctly identifies that it’s not present in the array of numbers. This strictness is crucial for avoiding unexpected behavior in your applications.

Real-World Examples

Let’s explore some practical scenarios where `Array.includes()` can be applied.

1. Checking User Permissions

Imagine you’re building a web application with different user roles (e.g., ‘admin’, ‘editor’, ‘viewer’). You can use `Array.includes()` to check if a user has a specific permission:

const userRoles = ['admin', 'editor'];

function canEdit(roles) {
  return roles.includes('editor');
}

console.log(canEdit(userRoles)); // Output: true

if (canEdit(userRoles)) {
  console.log('User can edit content.');
} else {
  console.log('User cannot edit content.');
}

2. Validating User Input

You can use `Array.includes()` to validate user input against a list of allowed values:

const allowedColors = ['red', 'green', 'blue'];

function isValidColor(color) {
  return allowedColors.includes(color);
}

console.log(isValidColor('green')); // Output: true
console.log(isValidColor('yellow')); // Output: false

3. Filtering Data

While `Array.includes()` doesn’t directly filter data, you can use it in conjunction with other array methods like `Array.filter()` to achieve filtering based on data existence:

const productIds = [1, 2, 3, 4, 5];
const cartIds = [2, 4, 6];

const productsInCart = productIds.filter(id => cartIds.includes(id));

console.log(productsInCart); // Output: [2, 4]

`Array.includes()` vs. `Array.indexOf()`

Before `Array.includes()` was introduced (in ES7), developers often used `Array.indexOf()` to check for the presence of an element in an array. While `Array.indexOf()` can achieve the same result, `Array.includes()` is generally preferred for its clarity and readability.

Here’s how `Array.indexOf()` works:

const fruits = ['apple', 'banana', 'orange'];

if (fruits.indexOf('banana') !== -1) {
  console.log('Banana is in the array.');
}

if (fruits.indexOf('kiwi') !== -1) {
  console.log('Kiwi is in the array.'); // This will not execute.
}

As you can see, with `indexOf()`, you need to check if the returned index is not equal to -1. `Array.includes()` simplifies this by returning a boolean directly. `indexOf()` also has the limitation of not being able to correctly identify `NaN` values, whereas `includes()` can.

Here’s the difference with `NaN`:

const numbers = [1, NaN, 3];

console.log(numbers.indexOf(NaN)); // Output: -1 (incorrect)
console.log(numbers.includes(NaN)); // Output: true (correct)

Common Mistakes and How to Avoid Them

While `Array.includes()` is straightforward, there are a few common pitfalls to be aware of:

1. Case Sensitivity

As mentioned earlier, `Array.includes()` is case-sensitive. Make sure the case of the searchElement matches the case of the values in the array. If you need to perform a case-insensitive check, you’ll need to convert both the searchElement and the array elements to the same case before comparison:

const fruits = ['Apple', 'banana', 'orange'];
const searchFruit = 'apple';

const includesFruit = fruits.some(fruit => fruit.toLowerCase() === searchFruit.toLowerCase());

console.log(includesFruit); // Output: true

2. Data Type Mismatches

Be mindful of data types. Comparing a number with a string will always return false. Ensure that the searchElement has the same data type as the values in the array.

3. Incorrect Indexing with `fromIndex`

When using the fromIndex parameter, remember that it specifies the starting index for the search, not the ending index. Also, if fromIndex is greater than or equal to the array’s length, includes() will return false because the search will never begin.

const numbers = [1, 2, 3, 4, 5];

console.log(numbers.includes(3, 3)); // Output: false (starts at index 3, checks only 4 and 5)
console.log(numbers.includes(3, 2)); // Output: true
console.log(numbers.includes(3, 5)); // Output: false (fromIndex is out of bounds)

4. Forgetting to Handle Empty Arrays

If you’re working with arrays that might be empty, `Array.includes()` will correctly return false. However, make sure your code handles this scenario gracefully, especially if you’re using the result in further operations.

const emptyArray = [];
console.log(emptyArray.includes('anything')); // Output: false

Step-by-Step Instructions

Let’s solidify your understanding with a practical example. We’ll create a simple function to check if a username exists in a list of registered users.

  1. Define the Registered Users: Create an array to store the registered usernames.
const registeredUsers = ['johnDoe', 'janeDoe', 'peterPan'];
  1. Create the Function: Define a function that takes a username as input and checks if it exists in the registeredUsers array using Array.includes().
function isUserRegistered(username) {
  return registeredUsers.includes(username);
}
  1. Test the Function: Test the function with different usernames.
console.log(isUserRegistered('johnDoe')); // Output: true
console.log(isUserRegistered('michaelScott')); // Output: false

This simple example demonstrates how you can effectively use `Array.includes()` in a real-world scenario.

Key Takeaways

  • Array.includes() is a concise and readable way to check if an array contains a specific value.
  • It returns a boolean value, making it easy to use in conditional statements.
  • The optional fromIndex parameter allows you to specify the starting position for the search.
  • `Array.includes()` is case-sensitive and considers data types.
  • It’s generally preferred over Array.indexOf() for its clarity and handling of `NaN`.

FAQ

  1. Can I use `Array.includes()` with objects?
    Yes, you can. However, `Array.includes()` will check for object equality by reference, not by value. This means it will only return true if you are comparing the same object instance. If you need to check for object equality based on their properties, you’ll need to implement a custom comparison logic, typically using methods like `JSON.stringify()` or by manually comparing the properties of the objects.
  2. Does `Array.includes()` work with arrays of arrays?
    Yes, `Array.includes()` works with arrays of arrays, but, like objects, it checks for equality by reference. If you have an array of arrays and want to find a specific sub-array, the sub-array must be the exact same instance in memory.
  3. Is `Array.includes()` supported in all browsers?
    Yes, `Array.includes()` is widely supported across all modern browsers, including Chrome, Firefox, Safari, Edge, and Internet Explorer 10 and above.
  4. How does `Array.includes()` handle the value `undefined`?
    `Array.includes()` will correctly identify the presence of `undefined` in an array.
  5. What is the time complexity of `Array.includes()`?
    The time complexity of `Array.includes()` is O(n) in the worst case, where n is the number of elements in the array. This means that in the worst-case scenario, the method might need to iterate through the entire array to find the searchElement.

Understanding and utilizing `Array.includes()` is a fundamental step in becoming proficient in JavaScript. Its simplicity and effectiveness make it an invaluable tool for any developer working with arrays. Whether you are validating user input, managing permissions, or filtering data, `Array.includes()` provides a clean and concise way to determine data existence, making your code more readable and maintainable. By mastering this method, you’ll be well-equipped to tackle a wide range of array-related tasks with confidence and efficiency. Embrace its straightforward nature, and you’ll find yourself reaching for it time and time again in your JavaScript endeavors. Armed with this knowledge, you are now ready to seamlessly integrate `Array.includes()` into your projects, simplifying your code and enhancing your ability to work with data in JavaScript.

More posts