JavaScript Element matches() Method

What You’ll Learn

Element.matches() is an instance method that tests whether the element would be selected by a CSS selector string. It returns true or false—perfect for filtering lists, conditional styling logic, and loops. Learn the MDN birds example, comparison with closest(), and five try-it labs aligned with MDN.

Introduction

When you loop through a list of elements, you often need a quick yes/no answer: “Does this node match my CSS rule?” Before matches(), developers checked className strings or wrote custom attribute tests.

matches(selectors) delegates that work to the browser’s CSS engine. Pass any valid selector—class, tag, ID, attribute, or pseudo-class—and get a boolean back. MDN: the method tests whether the element would be selected by the specified CSS selector.

This page is part of JavaScript Element. Related selector APIs include closest() and getElementsByClassName().

Understanding the matches() Method

Calling el.matches(selectors) asks the browser whether el would match if you ran that selector against the document.

• It is an instance method on Element.
• Tests only the element you call it on—no ancestor walk (MDN).
• Returns true if the element matches, otherwise false (MDN).
• Accepts the same selector strings as querySelector and querySelectorAll.
• Throws SyntaxError if selectors is not valid CSS (MDN).
• Formerly known as matchesSelector() in older drafts; also had vendor prefixes (webkitMatchesSelector, etc.).

📝 Syntax

General form of Element.matches (MDN):

matches(selectors)

Parameters

Return value

Exceptions

• SyntaxError DOMException — thrown if selectors cannot be parsed as a valid CSS selector list (MDN).

Common patterns

// MDN birds example
for (const bird of document.querySelectorAll("li")) {
  if (bird.matches(".endangered")) {
    console.log(`The ${bird.textContent} is endangered!`);
  }
}

// Class check
if (card.matches(".active")) { /* ... */ }

// Compound selector
if (btn.matches("button.primary:enabled")) { /* ... */ }

// Attribute selector
if (link.matches("[href^='https']")) { /* ... */ }

Examples Gallery

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

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

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

The Philippine eagle is endangered!

const card = document.querySelector(".card");

console.log(card.matches(".active"));  // false
card.classList.add("active");
console.log(card.matches(".active"));  // true

false
true

const item = document.querySelector("li.endangered");

console.log(item.matches("li"));           // true
console.log(item.matches("li.endangered")); // true
console.log(item.matches("div"));         // false

true
true
false

const li = document.querySelector("li");
const div = document.querySelector("div");

console.log(li.matches(":not(div)"));  // true
console.log(div.matches(":not(div)")); // false

true
false

const buttons = document.querySelectorAll("button");
const enabled = [];

for (const btn of buttons) {
  if (btn.matches("button:not([disabled])")) {
    enabled.push(btn.textContent);
  }
}

console.log(enabled.join(", "));
// "Save, Cancel"

Save, Cancel

🚀 Common Use Cases

• Filtering a NodeList or array of elements in a loop (MDN birds example).
• Conditional logic based on CSS classes, tags, or attributes.
• Validating form controls: input.matches(":invalid").
• Checking button state: btn.matches(":enabled").
• Feature-detecting styled components: el.matches("[data-theme='dark']").
• Replacing manual className string checks with full CSS selectors.

📝 Notes

• Not Deprecated, Experimental, or Non-standard on MDN (Baseline Widely available, April 2017).
• Returns a boolean — never null (unlike closest()).
• Invalid selectors throw SyntaxError—validate dynamic selectors carefully.
• Tests only the current element; use closest() to search ancestors.
• Related selector APIs: querySelector(), querySelectorAll(), closest() (MDN).
• Related: closest(), getElementsByClassName(), insertAdjacentText(), JavaScript hub.

💡 Best Practices