Document.querySelector()

Die Methode querySelector() von Document gibt das erste Element innerhalb eines Dokuments zurück, welches dem angegebenen Selektor bzw. Selektoren entspricht. Wurden keine Übereinstimmungen gefunden wird null zurückgegeben.

Hinweis: Der Abgleich erfolgt indem sämtliche Knoten des Dokuments und deren Unterknoten der Reihe nach mittels Tiefensuche in Hauptreihenfolge (depth-first pre-order) durchlaufen werden.

Syntax

element = document.querySelector(selectors);

Parameter

selectors
Ein DOMString mit einem oder mehreren Selektoren die abgeblichen werden sollen. Dieser String muss ein gültiger CSS-Selektor-String sein. Ist dies nicht der Fall, wird eine SYNTAX_ERR Exception ausgelöst. Weitere Informationen zu Selektoren und deren Verwaltung finden Sie unter DOM Elemente mittels Selektoren ermitteln.

Hinweis: Zeichen, die nicht zur Standard-CSS-Syntax gehören, müssen mit einem Backslash-Zeichen maskiert werden. Da JavaScript auch Backslash-Escape-Anweisungen verwendet, müssen Sie beim Schreiben von String-Literalen mit diesen Zeichen besonders vorsichtig sein. Weitere Informationen finden Sie unter Sonderzeichen maskieren.

Rückgabewert

Ein Element-Objekt, das das erste Element des Dokuments darstellt, das der angegebenen Gruppe von CSS-Selektoren entspricht, oder null, wenn keine Übereinstimmungen vorhanden sind.

Wenn Sie eine Liste aller Elemente benötigen, die mit den angegebenen Selektoren übereinstimmen, verwenden Sie stattdessen querySelectorAll().

Exceptions

SYNTAX_ERR
Die Syntax der angegebenen Selektoren ist ungültig.

Nutzungshinweise

Wenn der angegebene Selektor mit einer ID übereinstimmt, die im Dokument fälschlicherweise mehrmals vorkommt, wird das erste Element mit dieser ID zurückgegeben.

CSS-Pseudoelemente geben niemals Elemente zurück, wie in der Selektoren-API angegeben.

Sonderzeichen maskieren

Um mit einer ID oder Selektoren abzugleichen, die nicht der Standard-CSS-Syntax entsprechen (z. B. durch einen unzulässigen Doppelpunkt oder Leerzeichen), müssen Sie das Zeichen mit einem Backslash ("\") maskieren. Da der Backslash selbst ebenfalls ein Maskierungszeichen in JavaScript ist, müssen Sie ihn bei der Eingabe eines Stringliterals zweimal maskieren (einmal für den JavaScript String und einmal für querySelector()):

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

<script>
  console.log('#foo\bar');               // "#fooar" (\b is the backspace control character)
  document.querySelector('#foo\bar');    // Does not match anything

  console.log('#foo\\bar');              // "#foo\bar"
  console.log('#foo\\\\bar');            // "#foo\\bar"
  document.querySelector('#foo\\bar'); // Match the first div

  document.querySelector('#foo:bar');    // Does not match anything
  document.querySelector('#foo\\:bar');  // Match the second div
</script>

Beispiele

Erstes Element ermitteln, das mit einer Klasse übereinstimmt

In diesem Beispiel wird das erste Element im Dokument mit der Klasse "myclass" zurückgegeben:

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

Ein komplexerer Selektor

Selektoren können auch sehr mächtig sein, wie das folgende Beispiel zeigt. Hier wird das erste <input>-Element mit dem Namen "login" (<input name="login"/>) innerhalb eines <div>, dessen Klasse "user-panel main" ist (<div class="user-panel main">), im Dokument zurückgegeben:

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

Spezifikationen

Specification Status Comment
Selectors API Level 2
Die Definition von 'document.querySelector()' in dieser Spezifikation.
Veraltet  
Selectors API Level 1
Die Definition von 'document.querySelector()' in dieser Spezifikation.
Veraltet Initiale Definition

Browserkompatibilität

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid WebviewChrome für AndroidFirefox für AndroidOpera für AndroidSafari auf iOSSamsung Internet
querySelectorChrome Vollständige Unterstützung 1Edge Vollständige Unterstützung 12Firefox Vollständige Unterstützung 3.5IE Vollständige Unterstützung 8Opera Vollständige Unterstützung 10Safari Vollständige Unterstützung 3.2WebView Android Vollständige Unterstützung JaChrome Android Vollständige Unterstützung JaFirefox Android Vollständige Unterstützung JaOpera Android Vollständige Unterstützung 10.1Safari iOS Vollständige Unterstützung 3.2Samsung Internet Android ?

Legende

Vollständige Unterstützung  
Vollständige Unterstützung
Kompatibilität unbekannt  
Kompatibilität unbekannt

Siehe auch