Element: matches() method

{{APIRef("DOM")}}

The matches() method of the {{domxref("Element")}} interface tests whether the element would be selected by the specified CSS selector.

Syntax

matches(selectors)

Parameters

• selectors
  • : A string containing valid CSS selectors to test the {{domxref("Element")}} against.

Return value

true if the {{domxref("Element")}} matches the selectors. Otherwise, false.

Exceptions

• SyntaxError {{domxref("DOMException")}}
  • : Thrown if selectors cannot be parsed as a CSS selector list.

Examples

HTML

<ul id="birds">
  <li>Orange-winged parrot</li>
  <li class="endangered">Philippine eagle</li>
  <li>Great white pelican</li>
</ul>

JavaScript

const birds = document.querySelectorAll("li");

for (const bird of birds) {
  if (bird.matches(".endangered")) {
    console.log(`The ${bird.textContent} is endangered!`);
  }
}

This will log "The Philippine eagle is endangered!" to the console, since the element has indeed a class attribute with value endangered.

Specifications

{{Specifications}}

Browser compatibility

{{Compat}}

See also

• CSS selectors module
• Other {{domxref("Element")}} methods that take selectors: {{domxref("Element.querySelector()")}}, {{domxref("Element.querySelectorAll()")}}, and {{domxref("element.closest()")}}.