JavaScript Element matches() Method
Definition
The Element.matches() method tests whether this element would be selected by a CSS selector (MDN). It returns true or false.
Pass the required arguments shown below. Check return values and browser support before you rely on the result.
Syntax
Call el.matches. Start with this line.
| Call | What it does |
|---|
el.matches(selectors) | Primary signature. |
el.matches(...) | Call with the arguments your case needs. |
Built into the browser. Call matches(...) on an Element â no import required.
Library declarations
Parameters
| Parameter | Description |
|---|
| selectors | Required. Valid CSS selector string |
Return Value
| Return Value | Description |
|---|
| * | true or false |
JavaScript Examples
Example 1 — Filter With matches() (MDN)
Loop list items and log only elements that match .endangered.
const birds = document.querySelectorAll("li");
const out = document.getElementById("out");
const lines = [];
for (const bird of birds) {
if (bird.matches(".endangered")) {
lines.push("The " + bird.textContent + " is endangered!");
}
}
out.textContent = lines.join("\\n") || "(none)";
The Philippine eagle is endangered!
How It Works
- Collect candidates.
querySelectorAll("li") returns every list item. - Test each one.
matches(".endangered") is a boolean check. - Keep matches only. The eagle has that class; others do not.
- Show the result. Same idea as MDNâs console log.
Example 2 — True / False Check
Ask whether one element matches a selector.
const btn = document.getElementById("save");
const out = document.getElementById("out");
out.textContent = String(btn.matches("button[type='submit']"));
How It Works
- Grab one element. Here, the save button.
- Pass attribute CSS.
button[type='submit'] is a normal selector. - Get a boolean.
true means this node would be selected. - Branch freely. Use it in
if, filters, or guards.
Example 3 — Click Filter With matches()
Ignore clicks unless the target itself is a .item button.
const list = document.getElementById("list");
const out = document.getElementById("out");
list.addEventListener("click", (event) => {
const el = event.target;
if (!(el instanceof Element) || !el.matches("button.item")) return;
out.textContent = "clicked " + el.textContent;
});
How It Works
- Listen on a parent. One handler covers many children.
- Test the target.
matches("button.item") requires the exact node type. - Return early when the click is on something else.
- Prefer
closest() if clicks may land on nested text/spans inside the button.
Compatibility
Browser Support
Element.matches() is Baseline Widely available on MDN (across browsers since April 2017). It is not Deprecated, Experimental, or Non-standard.
✓ Baseline Widely available
Element.matches()
Test whether an element matches a CSS selector. Widely available since 2017.
Google Chrome Yes
Supported
Mozilla Firefox Yes
Supported
Apple Safari Yes
Supported
Microsoft Edge Yes
Supported
Opera Yes
Supported
Internet Explorer IE9+ (msMatchesSelector)
Partialmatches() Baseline
Bottom line: Safe for modern browsers. Prefer matches() over vendor-prefixed helpers. See the MDN matches() reference.
Frequently Asked Questions
MDN: it tests whether the element would be selected by the given CSS selector string. It returns true if the element matches, otherwise false.
No. MDN marks Element.matches() as Baseline Widely available (across browsers since April 2017). It is not Deprecated, Experimental, or Non-standard.
A boolean: true if the element matches the selectors, false if it does not (MDN).
matches() tests only the current element. closest() walks up through ancestors (including self) and returns the first matching Element or null.
Yes. matches() accepts the same valid CSS selector strings as querySelector and querySelectorAll (MDN).
A SyntaxError DOMException is thrown if selectors cannot be parsed as a valid CSS selector list (MDN).
Next: moveBefore()
Continue with the Element moveBefore() method.
About the author
Developer, cloud engineer, and technical writer
I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.
14 people found this page helpful
