files/en-us/web/api/element/queryselectorall/index.md
{{APIRef("DOM")}}
The {{domxref("Element")}} method querySelectorAll()
returns a static (not live) {{domxref("NodeList")}} representing a list of elements
matching the specified group of selectors which are descendants of the element on which
the method was called.
querySelectorAll(selectors)
selectors
: A string containing one or more selectors to match. This string
must be a valid CSS selector string; if it isn't, a SyntaxError exception
is thrown.
Note that the HTML specification does not require attribute values to be valid CSS identifiers. If a class or id attribute value is not a valid CSS identifier, then you must escape it before using it in a selector, either by calling {{domxref("CSS.escape_static", "CSS.escape()")}} on the value, or using one of the techniques described in Escaping characters. See Escaping attribute values for an example.
The selectors are applied to the entire document, not just the particular element on which querySelectorAll() is called. To restrict the selector to the element on which querySelectorAll() is called, include the {{cssxref(":scope")}} pseudo-class at the start of the selector. See the selector scope example.
A non-live {{domxref("NodeList")}} containing one {{domxref("Element")}} object for each descendant node that matches at least one of the specified selectors. The elements are in document order — that is, parents before children, earlier siblings before later siblings.
[!NOTE] If the specified
selectorsinclude a CSS pseudo-element, the returned list is always empty.
SyntaxError {{domxref("DOMException")}}
selectors string is not valid.This example uses the attribute selector to select multiple elements with a data-name data attribute that contains "funnel-chart-percent".
<section class="box" id="sect1">
<div data-name="funnel-chart-percent1">10.900%</div>
<div data-name="funnel-chart-percent2">3700.00%</div>
<div data-name="funnel-chart-percent3">0.00%</div>
</section>
const refs = [
...document.querySelectorAll(`[data-name*="funnel-chart-percent"]`),
];
To obtain a {{domxref("NodeList")}} of all of the {{HTMLElement("p")}} elements
contained within the element myBox:
const matches = myBox.querySelectorAll("p");
This example returns a list of all {{HTMLElement("div")}} elements within
myBox with a class of either note or alert:
const matches = myBox.querySelectorAll("div.note, div.alert");
Here, we get a list of the document's <p> elements whose immediate
parent element is a {{HTMLElement("div")}} with the class "highlighted" and
which are located inside a container whose ID is "test".
const container = document.querySelector("#test");
const matches = container.querySelectorAll("div.highlighted > p");
This example uses an attribute selector to return a list of the {{HTMLElement("iframe")}} elements in the document
that contain an attribute named "data-src":
const matches = document.querySelectorAll("iframe[data-src]");
Here, an attribute selector is used to return a list of the list items contained within
a list whose ID is "user-list" which have a "data-active"
attribute whose value is "1":
const container = document.querySelector("#user-list");
const matches = container.querySelectorAll("li[data-active='1']");
Once the {{domxref("NodeList")}} of matching elements is returned, you can examine it
just like any array. If the array is empty (that is, its length property is
0), then no matches were found.
Otherwise, you can use standard array notation to access the contents of the list. You can use any common looping statement, such as:
const highlightedItems = userList.querySelectorAll(".highlighted");
highlightedItems.forEach((userItem) => {
deleteUser(userItem);
});
[!NOTE]
NodeListis not a genuine array, that is to say it doesn't have array methods likeslice,some,map, etc. To convert it into an array, tryArray.from(nodeList).
The querySelectorAll() method applies its selectors to the whole document: they are not scoped to the element on which the method is called. To scope the selectors, include the {{cssxref(":scope")}} pseudo-class at the start of the selector string.
In this example the HTML contains:
#select and #select-scope<div> elements: #outer, #subject, and #inner<pre> element which the example uses for output.<button id="select">Select</button>
<button id="select-scope">Select with :scope</button>
<div id="outer">
#outer
<div id="subject">
#subject
<div id="inner">#inner</div>
</div>
</div>
<pre id="output"></pre>
div {
margin: 0.5rem;
padding: 0.5rem;
border: 3px lightseagreen solid;
border-radius: 5px;
font-family: monospace;
}
pre,
button {
margin: 0.5rem;
padding: 0.5rem;
}
In the JavaScript, we first select the #subject element.
When the #select button is pressed, we call querySelectorAll() on #subject, passing "#outer #inner" as the selector string.
When the #select-scope button is pressed, we again call querySelectorAll() on #subject, but this time we pass ":scope #outer #inner" as the selector string.
const subject = document.querySelector("#subject");
const select = document.querySelector("#select");
select.addEventListener("click", () => {
const selected = subject.querySelectorAll("#outer #inner");
output.textContent = `Selection count: ${selected.length}`;
});
const selectScope = document.querySelector("#select-scope");
selectScope.addEventListener("click", () => {
const selected = subject.querySelectorAll(":scope #outer #inner");
output.textContent = `Selection count: ${selected.length}`;
});
{{EmbedLiveSample("Selector scope", "", 300)}}
When we press "Select", the selector selects all elements with an ID of inner that also have an ancestor with an ID of outer. Note that even though #outer is outside the #subject element, it is still used in selection, so our #inner element is found.
When we press "Select with :scope", the :scope pseudo-class restricts the selector scope to #subject, so #outer is not used in selector matching, and we don't find the #inner element.
This example shows that if an HTML document contains an id which is not a valid CSS identifier, then we must escape the attribute value before using it in querySelectorAll().
In the following code, a {{htmlelement("div")}} element has an id of "this?element", which is not a valid CSS identifier, because the "?" character is not allowed in CSS identifiers.
We also have three buttons, and a {{htmlelement("pre")}} element for logging errors.
<div id="container">
<div id="this?element"></div>
</div>
<button id="no-escape">No escape</button>
<button id="css-escape">CSS.escape()</button>
<button id="manual-escape">Manual escape</button>
<pre id="log"></pre>
div {
background-color: blue;
margin: 1rem 0;
height: 100px;
width: 200px;
}
All three buttons, when clicked, try to select the <div>, and then set its background color to a random value.
"this?element" value directly."?" character using a backslash. Note that we must also escape the backslash itself, using another backslash, like: "\\?".const container = document.querySelector("#container");
const log = document.querySelector("#log");
function random(number) {
return Math.floor(Math.random() * number);
}
function setBackgroundColor(id) {
log.textContent = "";
try {
const elements = container.querySelectorAll(`#${id}`);
const randomColor = `rgb(${random(255)} ${random(255)} ${random(255)})`;
elements[0].style.backgroundColor = randomColor;
} catch (e) {
log.textContent = e;
}
}
document.querySelector("#no-escape").addEventListener("click", () => {
setBackgroundColor("this?element");
});
document.querySelector("#css-escape").addEventListener("click", () => {
setBackgroundColor(CSS.escape("this?element"));
});
document.querySelector("#manual-escape").addEventListener("click", () => {
setBackgroundColor("this\\?element");
});
Clicking the first button gives an error, while the second and third buttons work properly.
{{embedlivesample("escaping_attribute_values", "", 200)}}
{{Specifications}}
{{Compat}}