Returns the first element that is a descendant of the element on which it is invoked that matches the specified group of selectors.
Syntax
element = baseElement.querySelector(selectors);
Parameters
Return value
The first descendant element of baseElement
which matches the specified group of selectors
. The entire hierarchy of elements is considered when matching, including those outside the set of elements including baseElement
and its descendants; in other words, selectors
is first applied to the whole document, not the baseElement
, to generate an initial list of potential elements. The resulting elements are then examined to see if they are descendants of baseElement
. The first match of those remaining elements is returned by the querySelector()
method.
If no matches are found, the returned value is null
.
Exceptions
SyntaxError
- The specified
selectors
are invalid.
Examples
Let's consider a few examples.
Find a specific element with specific values of an attribute
In this first example, the first <style>
element which either has no type or has type "text/css" in the HTML document body is returned:
var el = document.body.querySelector("style[type='text/css'], style:not([type])");
The entire hierarchy counts
The next example, below, demonstrates that the hierarchy of the entire document is considered when applying selectors
, so that levels which are outside the specified baseElement
are still considered when locating matches.
HTML
<div>
<h5>Original content</h5>
<p>
inside paragraph
<span>inside span</span>
inside paragraph
</p>
</div>
<div>
<h5>Output</h5>
<div id="output"></div>
</div>
JavaScript
var baseElement = document.querySelector("p");
document.getElementById("output").innerHTML =
(baseElement.querySelector("div span").innerHTML);
Result
The result looks like this:
Notice how the "div span"
selector still matches the <span>
element, even though the baseElement
excludes the div
element which is part of the specified selector.
The :scope pseudo-class restores the expected behavior, only matching selectors on descendants of the baseElement.
More examples
See Document.querySelector()
for additional examples of the proper format for the selectors
.
Specifications
Specification | Status | Comment |
---|---|---|
DOM4 The definition of 'querySelectorAll()' in that specification. |
Obsolete | |
Selectors API Level 2 The definition of 'querySelectorAll()' in that specification. |
Obsolete | |
Selectors API Level 1 The definition of 'querySelectorAll()' in that specification. |
Obsolete |
Browser compatibility
Feature | Chrome | Edge | Firefox (Gecko) | Internet Explorer | Opera | Safari (WebKit) |
---|---|---|---|---|---|---|
Basic support | 1 | 12 | 3.5 (1.9.1) | 9[1][2] | (Yes) | (Yes) |
Feature | Android | Firefox Mobile (Gecko) | Firefox OS (Gecko) | IE Phone | Opera Mobile | Safari Mobile | Chrome for Android |
---|---|---|---|---|---|---|---|
Basic support | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) |
[1] querySelector()
is supported in IE8, but only for CSS 2.1 selectors.
[2] in IE8 and iE9 document must be in HTML5 mode (HTML5 doctype declaration present)