Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

Element.matches — testar um seletor CSS

Element.matches verifica se um determinado elemento corresponde a um seletor CSS. Devolve um valor booleano, não um elemento; uma sintaxe de seletor inválida provoca uma exceção.

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

Sintaxe

element.matches(selectors)

element.matches(selectors) testa o próprio element. O argumento selectors é uma cadeia de seletor CSS ou uma lista de seletores separados por vírgulas. O resultado é true se o elemento corresponder, ou false caso contrário.

O método não pesquisa os descendentes como querySelector() nem encontra um antepassado correspondente como closest(). O elemento não tem de estar ligado a um documento; ainda assim, os seletores que dependem das relações na árvore têm em conta o seu contexto real.

Um seletor inválido lança uma DOMException com o nome SyntaxError, em vez de devolver false.

Esta é uma API DOM definida pelo DOM Standard, não uma funcionalidade de ECMAScript. A presença de Node 24, por si só, não comprova que esta API de browser seja suportada.

Exemplos

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

Resultado

true
false
true
SyntaxError

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes