The matches()
method checks to see if the Element
would be selected by the provided selectorString
-- in other words -- checks if the element "is" the selector.
Syntax
var result = element.matches(selectorString);
Parameters
selectorString
is a string representing the selector to test.
Return value
result
is a Boolean
.
Exceptions
SYNTAX_ERR
- The specified selector string is invalid.
Example
<ul id="birds"> <li>Orange-winged parrot</li> <li class="endangered">Philippine eagle</li> <li>Great white pelican</li> </ul> <script type="text/javascript"> var birds = document.getElementsByTagName('li'); for (var i = 0; i < birds.length; i++) { if (birds[i].matches('.endangered')) { console.log('The ' + birds[i].textContent + ' is endangered!'); } } </script>
This will log "The Philippine eagle is endangered!" to the console, since the element has indeed a class
attribute with value endangered
.
Polyfill
For browsers that do not support Element.matches()
or Element.matchesSelector()
, but include support for document.querySelectorAll()
, a polyfill exists:
if (!Element.prototype.matches) { Element.prototype.matches = Element.prototype.matchesSelector || Element.prototype.mozMatchesSelector || Element.prototype.msMatchesSelector || Element.prototype.oMatchesSelector || Element.prototype.webkitMatchesSelector || function(s) { var matches = (this.document || this.ownerDocument).querySelectorAll(s), i = matches.length; while (--i >= 0 && matches.item(i) !== this) {} return i > -1; }; }
However, given the practicality of supporting older browsers, the following should suffice for most (if not all) practical cases (i.e. IE9+ support).
if (!Element.prototype.matches) { Element.prototype.matches = Element.prototype.msMatchesSelector || Element.prototype.webkitMatchesSelector; }
Specification
Specification | Status | Comment |
---|---|---|
DOM The definition of 'Element.prototype.matches' in that specification. |
Living Standard | Initial definition |
Browser compatibility
The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
matches | Chrome
Full support
33
| Edge
Full support
≤18
| Firefox
Full support
34
| IE
Full support
9
| Opera
Full support
21
| Safari
Full support
7
| WebView Android
Full support
4.4
| Chrome Android
Full support
33
| Firefox Android
Full support
34
| Opera Android
Full support
21
| Safari iOS
Full support
8
| Samsung Internet Android
Full support
2.0
|
Legend
- Full support
- Full support
- See implementation notes.
- See implementation notes.
- Uses a non-standard name.
- Uses a non-standard name.
See also
-
Other methods that take selectors:
element.querySelector()
andelement.closest()
.