Skip to main content

contains vs includes

• 3 min read
this || that JavaScript

Older Article

This article was published 5 years ago. Some information may be outdated or no longer applicable.

When you’re working with JavaScript arrays and want to check if an element exists, your gut instinct might reach for contains. Makes sense, right? And if you’re coming from another language (Java, for instance), you’d be used to calling contains on an ArrayList.

In JavaScript, the method we actually need is includes. That said, JavaScript does have a contains method too. It just does something different.

includes

There are four ways the includes() method can be used in JavaScript today:

  • with arrays
  • with strings
  • with TypedArrays
  • with IndexedDB

We’ll focus on the first two since those come up most often.

includes with arrays

includes() for arrays takes two parameters (the second one’s optional):

includes(elementToFind, index)

The elementToFind parameter does what you’d expect: it specifies which element we’re hunting for. The second parameter defines a position within the array where the search should begin. The includes() method returns a boolean.

If index is greater than or equal to array.length, the search won’t run and includes() automatically returns false.

includes with String

includes() also works with strings, performing a case-sensitive search to check whether a string appears inside a larger body of text. The signature and return value behave the same as before, except the second (optional) parameter is a position within the string rather than an array index. (The position is inclusive.)

A few examples for both versions sit below.

See the Pen includes by Cloudinary (@Cloudinary) on CodePen.

contains

Now that we’ve covered includes(), let’s turn to contains(). This method appears in a few places:

  • on a Node
  • on a DOMTokenList
  • as part of the WebExtension API

Let’s zoom in on the second one, because I hit a specific snag with it and it took me a while to figure out what I was doing wrong. First, the signature (for the DOMTokenList):

contains(token)

The method returns a boolean.

For our example, let’s say we have a simple h1 element with two CSS classes:

<h1 class="title important">My title</h1>

And we want to check programmatically whether a particular CSS class has been added. If it hasn’t, we’ll fix that:

const el = document.querySelector('h1');
if (!el.classList.contains('important')) {
  el.classList.append('important')
}

Here’s the thing. The DOMTokenList looks and feels like an array, but it isn’t one. Some properties and methods might trick you into thinking you’re dealing with an array, but it’s a separate interface. So instead of includes(), we need contains().

There are ways to convert a DOMTokenList (or any other DOM Node) into an array. But once we do that, contains() won’t work anymore. We’d have to switch back to includes().

const el = document.querySelector('h1');
const DOMTokenListAsArray = [...el.classList];

Hopefully this clears things up. I don’t have a particular use case where converting a DOMTokenList to an array would be necessary, because the available properties and methods give us enough to work with.

Check out the example below.

See the Pen contains by Cloudinary (@Cloudinary) on CodePen.