The Element.matches() method returns true if the element would be selected by the specified selector string; otherwise, returns false.

Syntax

var result = element.matches(selectorString); 
  • result holds the return value true or false.
  • selectorString is a string representing the selector to test.

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.

Exceptions

SYNTAX_ERR
The specified selector string is invalid.

Polyfill

For browsers that do not support Element.matches() or Element.matchesSelector(), but carry 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;
}

Specification

Specification Status Comment
DOM
The definition of 'Element.prototype.matches' in that specification.
Living Standard Initial definition

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox for AndroidOpera for AndroidiOS SafariSamsung Internet
Basic supportChrome Full support 34
Full support 34
Full support Yes
Alternate Name
Alternate Name Uses the non-standard name: webkitMatchesSelector
Edge Full support Yes
Full support Yes
Full support Yes
Alternate Name
Alternate Name Uses the non-standard name: webkitMatchesSelector
Full support Yes
Alternate Name
Alternate Name Uses the non-standard name: msMatchesSelector
Firefox Full support 34
Full support 34
Full support 44
Alternate Name
Alternate Name Uses the non-standard name: webkitMatchesSelector
Full support 3.6
Notes Alternate Name
Notes Prior to Firefox 4, invalid selector strings caused false to be returned instead of throwing an exception.
Notes See bug 1119718 for removal.
Alternate Name Uses the non-standard name: mozMatchesSelector
IE Full support 9
Alternate Name
Full support 9
Alternate Name
Alternate Name Uses the non-standard name: msMatchesSelector
Opera Full support 21
Full support 21
Full support 15
Alternate Name
Alternate Name Uses the non-standard name: webkitMatchesSelector
No support 11.5 — 15
Alternate Name
Alternate Name Uses the non-standard name: oMatchesSelector
Safari Full support 7
Full support 7
Full support 5
Alternate Name
Alternate Name Uses the non-standard name: webkitMatchesSelector
WebView Android Full support Yes
Full support Yes
Full support Yes
Alternate Name
Alternate Name Uses the non-standard name: webkitMatchesSelector
Chrome Android Full support 34
Full support 34
Full support Yes
Alternate Name
Alternate Name Uses the non-standard name: webkitMatchesSelector
Edge Mobile Full support Yes
Full support Yes
Full support Yes
Alternate Name
Alternate Name Uses the non-standard name: webkitMatchesSelector
Full support Yes
Alternate Name
Alternate Name Uses the non-standard name: msMatchesSelector
Firefox Android Full support 34
Full support 34
Full support 44
Alternate Name
Alternate Name Uses the non-standard name: webkitMatchesSelector
Full support 4
Notes Alternate Name
Notes See bug 1119718 for removal.
Alternate Name Uses the non-standard name: mozMatchesSelector
Opera Android Full support 21
Full support 21
Full support 15
Alternate Name
Alternate Name Uses the non-standard name: webkitMatchesSelector
No support 11.5 — 15
Alternate Name
Alternate Name Uses the non-standard name: oMatchesSelector
Safari iOS Full support 8
Full support 8
Full support Yes
Alternate Name
Alternate Name Uses the non-standard name: webkitMatchesSelector
Samsung Internet Android Full support Yes
Full support Yes
Full support Yes
Alternate Name
Alternate Name Uses the non-standard name: webkitMatchesSelector

Legend

Full support  
Full support
See implementation notes.
See implementation notes.
Uses a non-standard name.
Uses a non-standard name.

See also