How to Use the includes() Method in JavaScript

The includes() method is part of both the Array and String prototypes. This method accepts a search value as a parameter, and returns true if the value is either contained in the array on which it is called, or if it exists as a substring of the string object on which it is called.

This article introduces the basics of the includes() method for each prototype, as well as exploring the differences between the two.

A basic String.includes() example

The following example demonstrates basic usage of includes() when working with a String:

const str = 'This String includes the word includes';
console.log(str.includes('includes'));
// Expected output: true

In the example above, the includes() method is used to search the string variable const str for the word “includes”. As the value of const str contains the search string (included as the character combination i-n-c-l-u-d-e-s), the method returns true.

Important: includes() is case sensitive!!

Searching for “Includes” with a capital I will return false. Blank spaces are also taken into account when searching a String or an Array.

The includes() method searches strings using character combination matches. This is why blank spaces count as part of the pattern to detect, and why it is possible to search for fractions of words – or even single characters, as seen below:

console.log(str.includes('u'));
// Expected output: true
console.log(str.includes('u '));
// Expected output: false

In the above example, searching for the character ‘u’ using includes() returns true, as the character exists in the string.

However, searching for the character ‘u’ with a blank space following results in includes() returning false, as this combination of characters does not exist in const str.

Array.includes() basic example

This next example demonstrates how to use the Array version of includes():

const furniture = ['table', 'chair', 'cupboard', 'wardrobe', 'stool'];
console.log(furniture.includes('chair'));
// Expected output: true

In the example above the array const furniture includes the item chair. Thus, the includes() method returns true.

Similar to String.includes() above, the search method is also case-sensitive. This means that searching for “Chair” with a capital ‘C’ will return false. The same applies to search strings that include blank spaces – as none of the elements of the array include a space, any search string with a blank space will return false as a result.

Unlike its companion String.includes() method, Array.includes() does not allow you to search for a fraction of an item:

console.log(furniture.includes('cha'));
// Expected output: false

In the above example, while it is true that the search term – “cha” – is present in the element “chair” as the first set of characters, this method will still return false. This is because Array.includes() only allows you to search for whole items.

Syntax

As seen above, the syntax for the includes() method is straightforward – simply apply the includes() method to a String or an Array, and pass in the searchValue as an argument.

The includes() method also accepts a second parameter – startIndex – which indicates the location at which the search should begin.

The syntax of includes() is as follows:

String or Array.includes(searchValue, startIndex)

SearchValue:

The searchValue parameter represents the value to be searched for.

For String.includes – the argument must be a string.

For Array.includes – the argument can be of any primitive data type (excluding Symbol) and functions. More details on this are presented below in the section Possible search values for Arrays.

startIndex: The startIndex parameter specifies the index of the String or Array at which the search should begin. This parameter accepts a number, and has a default value of zero (0).

console.log(str.includes('includes', 16));
// Expected output: true

The example above uses const str from our previous example, but begins the search at index 16 instead of at the beginning. As this is in the middle of the first occurrence of the word “includes” in the source string, this first instance is not counted as a match. However, because const str ends with the character combination i-n-c-l-u-d-e-s, the method still returns true.

Tip: The String.charAt() method tells which character appears at a certain index.

console.log(str.charAt(16));
// Expected output: u

The character at Index 16 of const str is the character u in the first occurrence of the word “includes”.

Negative indices

Array.includes() can receive negative indices for the startIndex parameter. This causes the search starting position to count from the end of the array, instead of the beginning.

Note: Negative indices can only be used for Array.includes() – they are not applicable for String.includes()!

console.log(furniture.includes('chair', -2));
// Expected output: false

In the example above, the search of the furniture array begins at index -2. This represents the second-to-last element in the array. In the definition of const furniture, this represents the item “wardrobe”. As there is no occurrence of the item “chair” after the item “wardrobe” in const furniture, the includes() method returns false.

Differences between Array.includes() and String.includes()

There are two primary differences in how the includes() method behaves for the String and Array prototypes:

Array.includes() can accept negative indices for startIndex, while String.includes() cannot.

Array.includes() allows you to search for multiple data types, while String.includes() allows you to only search for Strings.

Possible search values for Arrays

Let’s explore Array.includes() in a bit more detail. To help, we’ll start by defining four variables:

const bigNum = 235326n;
const word = 'word';
const x = Symbol('foo');
const y = Symbol('bar');

In the example code above, const bigNum is of type BigInt , const word is of type String , and the other two (const x and const y) are Symbols.

Next, we’ll define a mixed array to use in our searches:

const mix = [56, true, undefined, null, 235326n, Symbol('foo'), y, word];

The array const mix represents a combination of various data types.

As was mentioned above, the data type used to search Arrays can be any primitive data type (Symbols excluded) and functions.

The examples below highlight the return values for searches of different data types in the const mix array:

console.log(mix.includes(56));     	// Expected output: true
console.log(mix.includes(true));        // Expected output: true
console.log(mix.includes(undefined));  	// Expected output: true
console.log(mix.includes(null));        // Expected output: true

The variable const bigNum stores a BigInt value. The value of this variable (235326n) appears in the Array const mix as a value. As seen in the examples below, we can search for this value either using the value, or a variable which stores this value (i.e. bigNum):

console.log(mix.includes(235326n));	// Expected output: true
console.log(mix.includes(bigNum)); 	// Expected output: true

The inclusion of a Symbol cannot be verified with the includes() method, neither by searching for the value itself (Symbol(‘foo’)) nor by searching for the variable which refers to this value (x).

console.log(mix.includes(Symbol('foo'))); // Expected output: false
console.log(mix.includes(x));      	  // Expected output: false

However, because the array contains a variable y which refers to Symbol(‘bar’), it is possible to use the includes() method to search for the presence of this variable and verify its inclusion:

console.log(mix.includes(y));      	// Expected output: true

Similarly, if a variable is an item in an array (as seen above with const word), you use Array.includes() to search for the value (i.e. ‘word’) stored in that variable:

console.log(mix.includes('word')); 	// Expected output: true

Note: You cannot use Array.includes() to search for either a sub-array or an Object.

Related Articles

JavaScript – How to Search Arrays

JavaScript – Arrays Explained

JavaScript – How to Use the substring Method