Element.querySelector()
The querySelector()
method of the Element
interface 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])");
Get direct descendants using the :scope pseudo-class
This example uses the :scope
pseudo-class to retrieve direct children of the parentElement
element.
HTML
<div>
<h6>Page Title</h6>
<div id="parent">
<span>Love is Kind.</span>
<span>
<span>Love is Patient.</span>
</span>
<span>
<span>Love is Selfless.</span>
</span>
</div>
</div>
CSS
span {
display:block;
margin-bottom: 5px;
}
.red span {
background-color: red;
padding:5px;
}
JavaScript
const parentElement = document.querySelector('#parent');
let allChildren = parentElement.querySelectorAll(":scope > span");
allChildren.forEach(item => item.classList.add("red"));
Result
The entire hierarchy counts
This example demonstrates that the hierarchy of the entire document is considered when
applying selectors
, so that levels 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 successfully matches the
<span>
element, even though the baseElement
's child nodes
do not include the <div>
element (it is still part of the specified
selector).
More examples
See Document.querySelector()
for additional examples of the proper
format for the selectors
.
Specifications
Specification |
---|
DOM Standard # ref-for-dom-parentnode-queryselectorall① |
Browser compatibility
BCD tables only load in the browser
See also
- Locating DOM elements using selectors
- Attribute selectors in the CSS Guide
- Attribute selectors in the MDN Learning Area
Element.querySelectorAll()
-
Document.querySelector()
andDocument.querySelectorAll()
-
DocumentFragment.querySelector()
andDocumentFragment.querySelectorAll()
-
Other methods that take selectors:
element.closest()
andelement.matches()
.