JavaScript element.matches()
last modified April 2, 2025
In this article, we explore the element.matches() method in
JavaScript. This method checks if an element matches a specific CSS selector,
making it invaluable for DOM traversal and event delegation.
Basic Definition
The element.matches() method returns a boolean indicating whether
the element would be selected by the specified CSS selector string. It's part of
the Element API and supported in all modern browsers.
This method is particularly useful for event delegation, where you need to check if an event target matches certain criteria. It accepts any valid CSS selector as its parameter, including complex selectors.
Basic element.matches()
This example demonstrates the basic usage of matches() to check element types.
<!DOCTYPE html>
<html>
<head>
<title>Basic matches()</title>
</head>
<body>
<div id="content">Hello there!</div>
<p class="message">This is a message.</p>
<script>
const div = document.getElementById('content');
const p = document.querySelector('.message');
console.log(div.matches('div')); // true
console.log(div.matches('#content')); // true
console.log(p.matches('div.message')); // false
</script>
</body>
</html>
In this basic example, we check if elements match different selectors. The div matches both 'div' and '#content' selectors, while the paragraph doesn't match a non-existent 'div.message' selector.
This demonstrates the fundamental usage of matches() to verify
element-selector relationships. The method returns true only if the element
would be selected by the given CSS selector.
Event Delegation with matches()
This example shows how to use matches() for efficient event delegation.
<!DOCTYPE html>
<html>
<head>
<title>Event Delegation</title>
</head>
<body>
<ul id="menu">
<li class="item">Home</li>
<li class="item active">Products</li>
<li class="item">About</li>
</ul>
<script>
document.getElementById('menu').addEventListener('click', function(e) {
if (e.target.matches('li.item')) {
console.log('Menu item clicked:', e.target.textContent);
}
if (e.target.matches('li.active')) {
console.log('Active item clicked!');
}
});
</script>
</body>
</html>
Here we use event delegation on a menu list. The click handler checks if the
target matches specific selectors using matches(). This approach
is more efficient than attaching handlers to each item individually.
The example shows how matches() enables selective event handling
based on element characteristics. It works with both single and multiple class
selectors.
Checking Complex Selectors
This example demonstrates matches() with complex CSS selector combinations.
<!DOCTYPE html>
<html>
<head>
<title>Complex Selectors</title>
</head>
<body>
<div class="container">
<p class="highlight">Important text</p>
<p>Normal text</p>
<a href="#" class="btn highlight">Button</a>
</div>
<script>
const elements = document.querySelectorAll('.container *');
elements.forEach(el => {
if (el.matches('p.highlight')) {
console.log('Highlighted paragraph:', el.textContent);
}
if (el.matches('a.btn')) {
console.log('Button element found');
}
if (el.matches(':not(.highlight)')) {
console.log('Element without highlight:', el.tagName);
}
});
</script>
</body>
</html>
This example shows matches() working with complex selectors. We
check for elements with multiple classes, specific combinations, and negation
pseudo-classes.
The method handles all CSS selector types, including attribute selectors, pseudo-classes, and combinators. This makes it powerful for precise element selection checks.
Dynamic Class Checking
This example demonstrates using matches() to check for dynamically added classes.
<!DOCTYPE html>
<html>
<head>
<title>Dynamic Classes</title>
<style>
.active { color: red; }
.hidden { display: none; }
</style>
</head>
<body>
<div id="box" class="box">Sample Content</div>
<button onclick="toggleClass()">Toggle Active</button>
<button onclick="checkStatus()">Check Status</button>
<script>
const box = document.getElementById('box');
function toggleClass() {
box.classList.toggle('active');
}
function checkStatus() {
const isActive = box.matches('.active');
console.log('Is box active?', isActive);
}
</script>
</body>
</html>
Here we toggle a class on an element and use matches() to check
its current state. The method provides a clean way to verify class presence
without directly accessing classList.
This approach is useful when you need to check complex selector conditions rather than just class presence. It works with any valid CSS selector, not just class selectors.
Form Validation with matches()
This example shows how to use matches() for form validation patterns.
<!DOCTYPE html>
<html>
<head>
<title>Form Validation</title>
</head>
<body>
<form id="userForm">
<input type="text" id="username"
pattern="[A-Za-z]{3,}"
title="3+ letters"
required>
<button type="submit">Submit</button>
</form>
<p id="message"></p>
<script>
document.getElementById('userForm').addEventListener('submit', function(e) {
e.preventDefault();
const input = document.getElementById('username');
const message = document.getElementById('message');
if (input.matches(':invalid')) {
message.textContent = 'Please enter a valid username (3+ letters)';
message.style.color = 'red';
} else {
message.textContent = 'Form submitted successfully!';
message.style.color = 'green';
}
});
</script>
</body>
</html>
In this form validation example, we use matches() with the
':invalid' pseudo-class to check input validity. This approach integrates
with HTML5 validation attributes like 'pattern' and 'required'.
The example demonstrates how matches() can work with
pseudo-classes that reflect element state. This provides a declarative
way to check validation status.
Source
MDN element.matches() Documentation
In this article, we have shown how to use element.matches()
in JavaScript. This method is essential for DOM traversal, event delegation,
and selector matching in modern web development.
Author
List all JS DOM tutorials.