Web/API/Element/matches

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
DOMThe definition of 'Element.prototype.matches' in that specification.	Living Standard	Initial definition

Browser compatibility

Update compatibility data on GitHub

	Desktop						Mobile
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
`matches`	Chrome Full support 33 Full support 33 Full support 4 Alternate Name' Alternate Name' Uses the non-standard name: `webkitMatchesSelector`	Edge Full support 15 Full support 15 Full support 12 Alternate Name' Alternate Name' Uses the non-standard name: `webkitMatchesSelector` Full support 12 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 4.4 Full support 4.4 Full support ≤37 Alternate Name' Alternate Name' Uses the non-standard name: `webkitMatchesSelector`	Chrome Android Full support 33 Full support 33 Full support 18 Alternate Name' Alternate Name' Uses the non-standard name: `webkitMatchesSelector`	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 14 Alternate Name' Alternate Name' Uses the non-standard name: `webkitMatchesSelector` No support 11.5 — 14 Alternate Name' Alternate Name' Uses the non-standard name: `oMatchesSelector`	Safari iOS Full support 8 Full support 8 Full support 4.2 Alternate Name' Alternate Name' Uses the non-standard name: `webkitMatchesSelector`	Samsung Internet Android Full support 2.0 Full support 2.0 Full support 1.0 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.