Document.querySelector()

O método querySelector() de Document retorna o primeiro Element dentro do documento que corresponde ao seletor, ou grupo de seleteores especificados. Se não há elementos que correspondem, null é devolvido como resultado.

Nota: A correspondência é feita através de uma travessia pre-order em profundidade dos nódulos do documento, a começar com o primeiro elemento da marcação do documento e iterando através de nódulos sequenciais por ordem do número de nódulos filhos.

Syntaxe

element = document.querySelector(selectors);

Parameteros

selectors
Um DOMString a conter um ou mais seletores para com que corresponder. Esta string tem de ser um seletor de CSS valido; se não é, uma exception SYNTAX_ERR é lançada. Veja Localizar elementos do DOM a usar seletores para saber mais sobre seletor e como os gerir.

Nota: Os carateres que não fazem parte da sintaxe padrão do CSS devem ser evitados ao usar um caráter de barra invertida. Uma vez que o JavaScript também usa barra invertida para escapar, deve ter especial cuidado ao escrever string literals usando estes carateres. Veja Escapar carateres especiais para obter mais informação.

Resultado

Um objeto HTMLElement a representar o primeiro elemento no documento que corresponde aos seletores de CSS, ou null se não há elementos correspondentes.

Se precisar de uma lista de todos os elementos que correspondem ao seletores especificados, deve usar querySelectorAll().

Exeções

SYNTAX_ERR
O syntaxe dos selectors especificados está incorrecto.

Notas de uso

Se o seletor especificado corresponde a um ID que é incorretamente utilizado mais que uma vez num documento, o primeiro elemento com esse ID será devolvido.

Pseudoelementos de CSS não devolvem elementos, como é especificado na API de seletores.

Escapar carateres especiais

Para corresponder a um ID ou seletor que não segue a sintaxe de CSS padrão (ao usar o caráter de dois pontos ou espaço incorretamente), deve escapar o caráter com uma barra invertida ("\"). Como a barra invertida também é um caráter de escapar no JavaScript, se a escrever numa string literal, tem de a escapar duas vezes (primeiro para a string do JavaScript, e depois para o querySelector()):

<div id="foo\bar"></div>
<div id="foo:bar"></div>

<script>
  console.log('#foo\bar');               // "#fooar" (\b é o caráter de controlo para a barra invertida)
  document.querySelector('#foo\bar');    // Corresponde a nada

  console.log('#foo\\bar');              // "#foo\bar"
  console.log('#foo\\\\bar');            // "#foo\\bar"
  document.querySelector('#foo\\\\bar'); // Corresponde ao primeiro div

  document.querySelector('#foo:bar');    // Corresponde a nada
  document.querySelector('#foo\\:bar');  // Corresponde ao segundo div
</script>

Exemplos

Encontrar o primeiro elemento que corresponde a uma classe

Neste exemplo, o primeiro elemento no documento com a classe myclass é devolvida:

var el = document.querySelector(".myclass");

Um seletor mais complexo

Seletores são muito poderosos, como demonstrado no seguinte exemplo. O primeiro elemento <input> com o nome "login" (<input name="login"/>) encontrado dentro dum <div> cuja classe é "user-panel main" (<div class="user-panel main">) no documento é devolvido:

var el = document.querySelector("div.user-panel.main input[name='login']");

Negação

Todos os strings de seletores de CSS são válidos, assim também é possivel ter seletores de negação:

var el = document.querySelector("div.user-panel:not(.main) input[name='login']");

Isto seléciona um input que tem um div com classe user-panel como parente, mas sem a classe main.

Especificações

Especificação Estado
DOM
The definition of 'document.querySelector()' in that specification.
Living Standard

Compatibilidade

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
querySelectorChrome Full support 1Edge Full support 12Firefox Full support 3.5IE Full support 8Opera Full support 10Safari Full support 3.2WebView Android Full support 1Chrome Android Full support 18Firefox Android Full support 4Opera Android Full support 10.1Safari iOS Full support 3Samsung Internet Android Full support 1.0

Legend

Full support  
Full support

Veja também