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.
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.
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
.
SyntaxError
DOMException
Thrown if the specified selectors
are invalid.
Let's consider a few examples.
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:
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>
js
const parentElement = document.querySelector("#parent"); let allChildren = parentElement.querySelectorAll(":scope > span"); allChildren.forEach((item) => item.classList.add("red"));
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>
js
const baseElement = document.querySelector("p"); document.getElementById("output").innerHTML = baseElement.querySelector("div span").innerHTML;
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).
See Document.querySelector()
for additional examples of the proper format for the selectors
.
Specification |
---|
DOM Standard # ref-for-dom-parentnode-queryselectorall① |
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Chrome | Edge | Firefox | Internet Explorer | Opera | Safari | WebView Android | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | |
querySelector |
1 | 12 | 3.5 | 98querySelector() is supported, but only for CSS 2.1 selectors. |
10 | 3.1 | 4.4 | 18 | 4 | 10.1 | 2 | 1.0 |
Element.querySelectorAll()
Document.querySelector()
and Document.querySelectorAll()
DocumentFragment.querySelector()
and DocumentFragment.querySelectorAll()
element.closest()
and element.matches()
.
© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/Element/querySelector