The Element method querySelectorAll() returns a static (not live) NodeList representing a list of elements matching the specified group of selectors which are descendants of the element on which the method was called.





A string containing one or more selectors to match against. This string must be a valid CSS selector string; if it's not, a SyntaxError exception is thrown. See Locating DOM elements using selectors for more information about using selectors to identify elements. Multiple selectors may be specified by separating them using commas.

Note: Characters which are not part of standard CSS syntax must be escaped using a backslash character. Since JavaScript also uses backslash escaping, special care must be taken when writing string literals using these characters. See Escaping special characters for more information.

Return value

A non-live NodeList containing one Element object for each descendant node that matches at least one of the specified selectors.

Note: If the specified selectors include a CSS pseudo-element, the returned list is always empty.


SyntaxError DOMException

Thrown if the syntax of the specified selectors string is not valid.


dataset selector & attribute selectors

<section class="box" id="sect1">
  <div class="funnel-chart-percent1">10.900%</div>
  <div class="funnel-chart-percent2">3700.00%</div>
  <div class="funnel-chart-percent3">0.00%</div>
// dataset selectors
const refs = [...document.querySelectorAll(`[data-name*="funnel-chart-percent"]`)];

// attribute selectors
// const refs = [...document.querySelectorAll(`[class*="funnel-chart-percent"]`)];
// const refs = [...document.querySelectorAll(`[class^="funnel-chart-percent"]`)];
// const refs = [...document.querySelectorAll(`[class$="funnel-chart-percent"]`)];
// const refs = [...document.querySelectorAll(`[class~="funnel-chart-percent"]`)];

Obtaining a list of matches

To obtain a NodeList of all of the <p> elements contained within the element "myBox":

const matches = myBox.querySelectorAll("p");

This example returns a list of all <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 <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 <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 "userlist" which have a "data-active" attribute whose value is "1":

const container = document.querySelector("#userlist");
const matches = container.querySelectorAll("li[data-active='1']");

Accessing the matches

Once the 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) => {

Note: NodeList is not a genuine array, that is to say it doesn't have array methods like slice, some, map, etc. To convert it into an array, try Array.from(nodeList).

User notes

querySelectorAll() behaves differently than most common JavaScript DOM libraries, which might lead to unexpected results.


Consider this HTML, with its three nested <div> blocks.

<div class="outer">
  <div class="select">
    <div class="inner"></div>


const select = document.querySelector('.select');
const inner = select.querySelectorAll('.outer .inner');
inner.length; // 1, not 0!

In this example, when selecting ".outer .inner" in the context the <div> with the class "select", the element with the class ".inner" is still found, even though .outer is not a descendant of the base element on which the search is performed (".select"). By default, querySelectorAll() only verifies that the last element in the selector is within the search scope.

The :scope pseudo-class restores the expected behavior, only matching selectors on descendants of the base element:

const select = document.querySelector('.select');
const inner = select.querySelectorAll(':scope .outer .inner');
inner.length; // 0


DOM Standard
# ref-for-dom-parentnode-queryselectorall①

Browser compatibility

BCD tables only load in the browser

See also