La méthode element.matches() renvoie true lorsque l'élément peut être sélectionné par le sélecteur défini par la chaîne passée en paramêtre; sinon, elle renvoie false.

Certains navigateurs implémentent cette méthode sous le nom matchesSelector() non-standardisé et préfixé.

Syntaxe

var result = element.matches(selectorString); 
  • result contient la valeur retournée true ou false.
  • selectorString est une chaîne définissant le sélecteur à tester sur l'élément.

Exemple

<ul id="birds">
  <li>perroquet amazone</li>
  <li class="endangered">aigle des Philippines</li>
  <li>pélican blanc</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('Le - ' + birds[i].textContent + '- est en voie de disparition !');
    }
  }
</script>

Ce code affichera l'alerte "Le - aigle des Philippines - est en voie de disparition !" sur la console, puisque l'élèment possède l'attribut class de valeur endangered.

Exceptions

SYNTAX_ERR
Lorsque la chaîne passée en paramêtre défini sélecteur invalide.

Polyfill

Pour les navigateurs qui ne supportent pas Element.matches() ou Element.matchesSelector(), mais fournissent le support de document.querySelectorAll(), il existe un polyfill :

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;            
        };
}

Cependant, étant donné la possibilité de prendre en charge les anciens navigateurs, les éléments suivants devraient suffire pour la plupart (sinon tous) des cas pratiques (c'est-à-dire le support IE9 +).

if (!Element.prototype.matches) {
    Element.prototype.matches = Element.prototype.msMatchesSelector;
}

Spécification

Spécification Status
DOM
La définition de 'Element.prototype.matches' dans cette spécification.
Standard évolutif

Compatibilité des navigateurs

Update compatibility data on GitHub
OrdinateurMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariWebview AndroidChrome pour AndroidEdge MobileFirefox pour AndroidOpera pour AndroidSafari pour iOSSamsung Internet
Support simpleChrome Support complet 34
Support complet 34
Support complet Oui
Autre nom
Autre nom Cette fonctionnalité utilise le nom non-standard : webkitMatchesSelector
Edge Support complet Oui
Support complet Oui
Support complet Oui
Autre nom
Autre nom Cette fonctionnalité utilise le nom non-standard : webkitMatchesSelector
Support complet Oui
Autre nom
Autre nom Cette fonctionnalité utilise le nom non-standard : msMatchesSelector
Firefox Support complet 34
Support complet 34
Support complet 44
Autre nom
Autre nom Cette fonctionnalité utilise le nom non-standard : webkitMatchesSelector
Support complet 3.6
Notes Autre nom
Notes Prior to Firefox 4, invalid selector strings caused false to be returned instead of throwing an exception.
Notes See bug 1119718 for removal.
Autre nom Cette fonctionnalité utilise le nom non-standard : mozMatchesSelector
IE Support complet 9
Autre nom
Support complet 9
Autre nom
Autre nom Cette fonctionnalité utilise le nom non-standard : msMatchesSelector
Opera Support complet 21
Support complet 21
Support complet 15
Autre nom
Autre nom Cette fonctionnalité utilise le nom non-standard : webkitMatchesSelector
Aucun support 11.5 — 15
Autre nom
Autre nom Cette fonctionnalité utilise le nom non-standard : oMatchesSelector
Safari Support complet 7
Support complet 7
Support complet 5
Autre nom
Autre nom Cette fonctionnalité utilise le nom non-standard : webkitMatchesSelector
WebView Android Support complet Oui
Support complet Oui
Support complet Oui
Autre nom
Autre nom Cette fonctionnalité utilise le nom non-standard : webkitMatchesSelector
Chrome Android Support complet 34
Support complet 34
Support complet Oui
Autre nom
Autre nom Cette fonctionnalité utilise le nom non-standard : webkitMatchesSelector
Edge Mobile Support complet Oui
Support complet Oui
Support complet Oui
Autre nom
Autre nom Cette fonctionnalité utilise le nom non-standard : webkitMatchesSelector
Support complet Oui
Autre nom
Autre nom Cette fonctionnalité utilise le nom non-standard : msMatchesSelector
Firefox Android Support complet 34
Support complet 34
Support complet 44
Autre nom
Autre nom Cette fonctionnalité utilise le nom non-standard : webkitMatchesSelector
Support complet 4
Notes Autre nom
Notes See bug 1119718 for removal.
Autre nom Cette fonctionnalité utilise le nom non-standard : mozMatchesSelector
Opera Android Support complet 21
Support complet 21
Support complet 15
Autre nom
Autre nom Cette fonctionnalité utilise le nom non-standard : webkitMatchesSelector
Aucun support 11.5 — 15
Autre nom
Autre nom Cette fonctionnalité utilise le nom non-standard : oMatchesSelector
Safari iOS Support complet 8
Support complet 8
Support complet Oui
Autre nom
Autre nom Cette fonctionnalité utilise le nom non-standard : webkitMatchesSelector
Samsung Internet Android Support complet Oui
Support complet Oui
Support complet Oui
Autre nom
Autre nom Cette fonctionnalité utilise le nom non-standard : webkitMatchesSelector

Légende

Support complet  
Support complet
Voir les notes d'implémentation.
Voir les notes d'implémentation.
Cette fonctionnalité utilise un nom non-standard.
Cette fonctionnalité utilise un nom non-standard.

Voir aussi

Étiquettes et contributeurs liés au document

Étiquettes : 
Contributeurs à cette page : loella16, nbouvrette, Watilin, vava
Dernière mise à jour par : loella16,