The String includes() method

includes() checks if a string contains the substring you pass as parameter. It returns true or false, nothing else.

It’s the most direct way to answer the question “does this string contain that string?”:

'JavaScript'.includes('Script') //true
'JavaScript'.includes('script') //false
'JavaScript'.includes('JavaScript') //true
'JavaScript'.includes('aSc') //true
'JavaScript'.includes('C++') //false

Notice the second line. The search is case sensitive. 'script' with a lowercase s does not match.

The method was added in ES2015. Before that, we had to check indexOf():

'JavaScript'.indexOf('Script') !== -1 //true

Both work, but includes() says what you mean without the -1 trick, so I always reach for it.

The second parameter

includes() also accepts an optional second parameter, an integer which indicates the position where to start searching from:

'a nice string'.includes('nice') //true
'a nice string'.includes('nice', 3) //false
'a nice string'.includes('nice', 2) //true

The word “nice” starts at index 2. If the search starts at index 3, we’re past its first letter, so the match fails.

How to do a case insensitive check

There’s no flag for it. The usual trick is to lowercase both strings before comparing:

const title = 'Working with JavaScript Strings'
title.toLowerCase().includes('javascript') //true

Edge cases

Every string includes the empty string:

'JavaScript'.includes('') //true

If you pass something that’s not a string, it gets converted to a string first:

'error 404: not found'.includes(404) //true

Be careful with regular expressions, though. They are the one exception. Passing a regex doesn’t get converted, it throws:

'JavaScript'.includes(/Script/)
//TypeError: First argument to String.prototype.includes must not be a regular expression

If you need pattern matching instead of a plain substring check, call test() on the regex:

/Script/.test('JavaScript') //true

A practical use: filtering

Since includes() returns a boolean, it fits naturally inside filter() callbacks. Here we keep only the post titles that mention a search term:

const titles = [
  'The String includes() method',
  'How to uppercase a string',
  'JavaScript loops explained'
]

titles.filter((title) => title.toLowerCase().includes('string'))
//['The String includes() method', 'How to uppercase a string']

One last thing. includes() tells you if the substring is there, not where. When you need the position, use indexOf(), which returns the index of the first match.

Want me to talk about your product? You can sponsor this site.