Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / JavaScript

Element.matches — testing a CSS selector

Element.matches tests whether a particular element matches a CSS selector. It returns a boolean, not an element; invalid selector syntax causes an exception.

Version: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntax

element.matches(selectors)

element.matches(selectors) tests element itself. The selectors argument is a CSS selector string or a comma-separated selector list. The result is true if the element matches, or false otherwise.

The method does not search descendants like querySelector() or find a matching ancestor like closest(). The element need not be attached to a document; selectors depending on tree relationships still use its actual surroundings.

An invalid selector throws a DOMException named SyntaxError, rather than returning false.

This is a DOM API defined by the DOM Standard, not an ECMAScript feature. The presence of Node 24 alone does not establish support for this browser API.

Examples

const element = document.createElement('button');
element.className = 'action';

console.log(element.matches('button.action'));
console.log(element.matches('.missing'));
console.log(element.matches('.missing, .action'));

try {
  element.matches('[');
} catch (error) {
  console.log(error.name);
}

Result

true
false
true
SyntaxError

The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.

Sources