Element.matches() — Methode · JavaScript-Referenz

Signatur

Element.prototype.matches(selectors)

Beschreibung

matches() prüft, ob ein Element auf einen CSS-Selektor passt. Das ist dieselbe Prüfung, die der Browser beim Anwenden von Stylesheets oder bei querySelectorAll() ausführt, nur umgekehrt: Du fängst beim Element an und fragst, ob der Selektor zutrifft. Das Element muss nicht im Dokument eingehängt sein.

Am häufigsten braucht man die Methode bei der Ereignis-Delegation: Ein einziger Listener hängt an einem Container, und mit event.target.matches(...) wird geprüft, ob das eigentlich angeklickte Element relevant ist. Sie eignet sich außerdem zum Filtern von Element-Listen, zum Erkennen von Zuständen wie :checked, :disabled oder :focus-visible und zur Feature-Erkennung von Pseudoklassen.

Du kannst beliebige gültige CSS-Selektoren übergeben, auch Selektorlisten mit Komma ("a, button"), Kombinatoren ("nav > a") und moderne Pseudoklassen wie :is(), :not() oder :has(). Kombinatoren werden gegen das gesamte Dokument bzw. den Baum ausgewertet, in dem das Element liegt, und nicht nur gegen dessen Unterbaum.

Parameter

Name	Typ	Default	Beschreibung
$selectors Pflicht	string		Ein gültiger CSS-Selektor oder eine Selektorliste mit Komma, gegen die das Element geprüft wird. Pseudo-Elemente wie `::before` passen nie.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn das Element auf den Selektor passt, sonst false.

Beispiele

Einfache Prüfung auf Klasse und Attribut

const btn = document.createElement('button');
btn.className = 'btn btn-primary';
btn.type = 'submit';

console.log(btn.matches('.btn-primary'));
console.log(btn.matches('button[type="submit"]'));
console.log(btn.matches('.btn-danger, a'));

true true false

Ereignis-Delegation in einer Liste

// <ul id="todos"><li>Einkaufen <button class="delete">×</button></li>...</ul>
const list = document.querySelector('#todos');

const onClick = (event) => {
  // Nur reagieren, wenn ein Löschen-Button angeklickt wurde
  if (event.target.matches('button.delete')) {
    event.target.closest('li').remove();
  }
};

list.addEventListener('click', onClick);

Elemente nach Zustand filtern

// Alle aktuell angehakten, nicht deaktivierten Checkboxen ermitteln
const boxes = [...document.querySelectorAll('input[type="checkbox"]')];
const selected = boxes
  .filter((el) => el.matches(':checked:not(:disabled)'))
  .map((el) => el.value);

console.log(selected);

["newsletter", "agb"] // abhängig vom Formularzustand

Feature-Erkennung und ungültige Selektoren abfangen

const supportsSelector = (selector) => {
  try {
    document.documentElement.matches(selector);
    return true;
  } catch {
    return false; // SyntaxError: Selektor unbekannt oder ungültig
  }
};

console.log(supportsSelector(':has(p)'));
console.log(supportsSelector('::-foo-bar'));

true // in modernen Browsern false

// Wichtig · Fallstricke

SyntaxError: Ist der Selektor ungültig, wirft die Methode eine DOMException vom Typ SyntaxError. Bei dynamischen oder von Benutzern eingegebenen Selektoren solltest du den Aufruf in try…catch packen.
Kein Element als Ziel: event.target kann auch ein Textknoten sein (z. B. bei SVG oder in älteren Browsern) oder das document. Diese Knoten haben kein matches(). Frag deshalb vorher event.target instanceof Element ab.
Verschachtelte Ziele: Klickt der Nutzer auf ein Kind-Element (z. B. ein <svg>-Icon im Button), liefert matches() für den Button-Selektor false. Für die Delegation ist event.target.closest(selector) meist robuster.
Sonderzeichen: IDs oder Klassen mit Sonderzeichen musst du mit CSS.escape() maskieren, zum Beispiel el.matches(`#${CSS.escape(id)}`).
Kompatibilität: Alle aktuellen Browser unterstützen die Methode ohne Präfix. Alte Versionen kannten nur webkitMatchesSelector, mozMatchesSelector oder msMatchesSelector (Internet Explorer 9–11). Ob neuere Pseudoklassen wie :has() funktionieren, hängt davon ab, welche Selektoren der jeweilige Browser unterstützt.

Siehe auch

Element.closest() Element.querySelector() Element.querySelectorAll() CSS.escape() EventTarget.addEventListener() Window.matchMedia() KeyboardLayoutMap.has()