Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / JavaScript

Element.matches — tester un sélecteur CSS

Element.matches vérifie si un élément donné correspond à un sélecteur CSS. La méthode renvoie un booléen, et non un élément ; une syntaxe de sélecteur invalide provoque une exception.

Version : ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntaxe

element.matches(selectors)

element.matches(selectors) teste element lui-même. L’argument selectors est une chaîne de sélecteur CSS ou une liste de sélecteurs séparés par des virgules. Le résultat est true si l’élément correspond, et false dans le cas contraire.

La méthode ne recherche pas parmi les descendants comme querySelector() et ne trouve pas un ancêtre correspondant comme closest(). L’élément n’a pas besoin d’être rattaché à un document ; les sélecteurs qui dépendent des relations dans l’arbre tiennent toutefois compte de son environnement réel.

Un sélecteur invalide déclenche une DOMException nommée SyntaxError, au lieu de renvoyer false.

Il s’agit d’une API DOM définie par le DOM Standard, et non d’une fonctionnalité ECMAScript. La seule présence de Node 24 ne prouve pas que cette API de navigateur est prise en charge.

Exemples

const element = document.createElement('button');
element.className = 'action';

console.log(element.matches('button.action'));
console.log(element.matches('.missing'));
console.log(element.matches('.missing, .action'));

try {
  element.matches('[');
} catch (error) {
  console.log(error.name);
}

Résultat

true
false
true
SyntaxError

Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.

Sources