JavaScript String includes() Method

What You’ll Learn

String.prototype.includes() performs a case-sensitive search and returns true or false if a substring is found (same API as MDN String.prototype.includes()). Learn the optional start position, empty-string behavior, why regex is not allowed, how it compares to indexOf(), five examples, and try-it labs.

Introduction

When you only need to know whether a string contains some text — not where it is — includes() is the clearest tool. It returns a boolean, so it fits naturally in if conditions and ternary expressions.

The search is always case-sensitive. For a case-insensitive check, lower-case both sides first. For the index of a match, use indexOf() instead. For patterns, use a regular expression API — includes() rejects regex arguments.

This page is part of JavaScript String Methods. Related topics include at() and length.

Understanding the includes() Method

includes(searchString, position) scans the receiver from position (default 0) looking for an exact substring match.

• Returns true or false — never an index.
• Matching is case-sensitive and exact (no wildcards).
• An empty searchString always yields true.
• A RegExp argument throws TypeError.

📝 Syntax

General forms of String.prototype.includes:

str.includes(searchString)
str.includes(searchString, position)

Parameters

• searchString — the substring to look for. Cannot be a regex. Non-regex values are coerced to strings (undefined becomes "undefined").
• position (optional) — zero-based index where the search starts. Defaults to 0.

Return value

A boolean. Special cases:

Common patterns

"Hello world".includes("world");           // true
"Hello world".includes("World");           // false
"Hello world".toLowerCase().includes("world"); // true

"abcdef".includes("cd", 2);                // true
"abcdef".includes("cd", 3);                // false

// Need the index? Use indexOf:
"abcdef".indexOf("cd");                    // 2

Examples Gallery

Examples follow MDN String.includes() patterns. Use View Output or Try It Yourself for each case.

const sentence = "The quick brown fox jumps over the lazy dog.";
const word = "fox";

`The word "${word}" ${
  sentence.includes(word) ? "is" : "is not"
} in the sentence`;
// 'The word "fox" is in the sentence'

The word "fox" is in the sentence

const str = "To be, or not to be, that is the question.";

str.includes("To be");        // true
str.includes("question");     // true
str.includes("nonexistent");  // false
str.includes("To be", 1);     // false  (starts searching after "T")
str.includes("TO BE");        // false  (case-sensitive)
str.includes("");             // true

true
true
false
false
false
true

"Blue Whale".includes("blue");  // false

"Blue Whale".toLowerCase().includes("blue");  // true

function includesIgnoreCase(str, needle) {
  return str.toLowerCase().includes(needle.toLowerCase());
}
includesIgnoreCase("JavaScript", "SCRIPT");  // true

false
true
true

const file = "report.final.pdf";

file.includes(".");           // true
file.includes(".", 7);        // true  (still finds ".pdf")
file.includes("report", 1);   // false (skipped the start)
file.includes("pdf", 12);     // true
file.includes("pdf", 13);     // false

true
true
false
true
false

"abc".includes("");     // true
"".includes("");        // true

"undefined".includes(undefined);  // true  (undefined → "undefined")
"abc".includes(undefined);        // false

try {
  "abc".includes(/a/);
} catch (e) {
  e.name;  // "TypeError"
}

// Prefer includes for boolean checks:
"hello".includes("ll");           // true
"hello".indexOf("ll") !== -1;     // true (older style)

true
true
true
false
TypeError
true
true

🚀 Common Use Cases

• Feature flags / keywords — detect a token in user input or config.
• File / URL checks — name.includes(".pdf") style filters.
• Guards in conditionals — readable if (msg.includes("error")).
• Case-insensitive filters — pair with toLowerCase().
• Not for positions — switch to indexOf / search when you need the index.
• Not for patterns — use regex when you need wildcards or flags.

📝 Notes

• includes() is case-sensitive.
• Passing a RegExp throws TypeError.
• Empty searchString always returns true.
• Omitting the needle (or passing undefined) searches for "undefined".
• position only changes where the search starts — not a “must begin at” rule.
• Use indexOf() when you need the match index.

💡 Best Practices