JavaScript String includes() Function – Checking if a String Contains a Substring

Definition and Usage

The includes() function for strings checks whether a given string contains a specified substring and returns true if it does, or false otherwise.

Using this function is very useful for checking whether a specific substring is included.

This function is case-sensitive when performing the search.

Basic Example

JavaScript

const str = "Nice to meet you! Welcome to codingCourses.";

console.log(str.includes("codingCourses")); // Output: true
console.log(str.includes("CODINGCOURSES")); // Output: false (case-sensitive)

In arrays, the includes() function checks whether a specific element is present in an array.

Syntax

str is the string to which the includes() function is applied.

Parameters

Parameters of the String `includes()` Function
`searchString`	The string to search for. This value must not be a regular expression. Any non–regular-expression value is coerced to a string. Therefore, if this argument is omitted or passed as `undefined`, `includes()` will search for the string `"undefined"`, which is generally not the intended behavior.
`position`	Optional. A `0`-based index indicating the position at which to begin the search. If omitted, the default value `0` is used. (String indexes start at `0`.)

Return Value

The function returns true if the given string contains the specified string, including an empty string (""). If it does not contain the specified string, it returns false.

Things to Keep in Mind

There are several important points to be aware of when using the includes() function.

Case Sensitivity

The includes() function is case-sensitive.

JavaScript

const haystack = "Hello, World!";
const needle = "world";

const isNeedle = haystack.includes(needle); // false (case-sensitive)

if (isNeedle) {
    console.log(`The string contains '${needle}'.`);
} else {
    console.log(`The string does not contain '${needle}'.`);
}

// Output: "The string does not contain 'world'."

Regular Expression Patterns Are Not Allowed

The search string must not be a regular expression. If a regular expression is passed, a TypeError is thrown.

JavaScript

const haystack = "Hello, World!";
const needle = /Hello/; // Must not be a regular expression. Throws a TypeError.

const isNeedle = haystack.includes(needle);

if (isNeedle) {
    console.log(`The string contains '${needle}'.`);
} else {
    console.log(`The string does not contain '${needle}'.`);
}

Empty String

An empty string ("") is considered to exist at both the start and end of every string. As a result, searching for an empty string always returns true.

JavaScript

const haystack = "Welcome!";
const needle = "";

const isNeedle = haystack.includes(needle);

console.log(isNeedle); // An empty string always returns true.

This behavior is based on the logical definition of strings. An empty string is considered to exist at the beginning and end of any string, so returning true for any string that starts or ends with an empty string is a natural result. For this reason, this concept is not unique to JavaScript and is commonly applied across many programming languages.

Practical Examples

The includes() function is useful when you need to check whether a string contains a specific substring. It is commonly used in search features and string-processing logic. Below are some practical examples of how to use includes().

Implementing a Search Feature

JavaScript

const text = "I like apples and bananas.";
const searchTerm = "apples";

if (text.includes(searchTerm)) {
    console.log(`The text contains the word '${searchTerm}'.`);
} else {
    console.log(`The text does not contain the word '${searchTerm}'.`);
}

// Output: "The text contains the word 'apples'."

String Filtering

JavaScript

const content = "This sentence contains an unwanted word.";
const unwantedWords = ["unwanted", "bad", "inappropriate"];

unwantedWords.forEach(unwantedWord => {
    if (content.includes(unwantedWord)) {
        let filteredContent = content.replace(unwantedWord, "***");
        console.log(filteredContent);
    }
});

// Output: "This sentence contains an *** word."

Code Explanation
The array forEach() function iterates over an array and processes each element using a callback function.

Code Explanation
The string replace() function searches for a specific part of a string and replaces it with another string.

Counting Occurrences of a Specific Substring

JavaScript

// Find the string "hello" without case sensitivity
const searchStr = "hello";
const str = "Hello, world! hello, universe!".toLowerCase();

let count = 0;
let startIndex = 0;

while (str.includes(searchStr, startIndex)) {
    count++;
    startIndex = str.indexOf(searchStr, startIndex) + 1;
}

console.log("Number of occurrences:", count);
// Output: Number of occurrences: 2

Code Explanation
The toLowerCase() function converts a string to lowercase and returns a new string.

Code Explanation
The while statement is a loop that repeatedly executes a block of code as long as the condition evaluates to true.

Code Explanation
The string indexOf() function searches for the given substring and returns the index of the first occurrence.