JavaScript Document querySelectorAll() Method

What You’ll Learn

document.querySelectorAll() is an instance method that returns a static NodeList of every element matching a CSS selector string (see MDN Document: querySelectorAll()). Learn multiple selectors, attribute lookups, forEach loops, SyntaxError / CSS.escape() handling, how it compares to querySelector() and live collections, and five try-it labs.

Introduction

Where querySelector stops at the first hit, querySelectorAll collects every match into a list you can loop. Pass the same CSS selector language you already know from stylesheets.

MDN: the result is a static (not live) NodeList in document order — parents before children, earlier siblings before later ones. No matches means an empty list (not null). If the selector includes a CSS pseudo-element, the list is always empty.

Related tutorials: querySelector(), Element.querySelectorAll(), getElementsByClassName(), getElementById().

Understanding document.querySelectorAll()

An instance method on the page’s document object (ParentNode mixin) that looks up all matching elements (MDN).

• selectors — a valid CSS selector string; invalid syntax throws SyntaxError (MDN).
• Return value — static NodeList of matching Elements, or empty if none (MDN).
• Order — document order (MDN).
• Static — not live; later DOM changes do not update the list (MDN).
• Pseudo-elements — always yield an empty list (MDN).
• Escape special ids — use CSS.escape() when needed (MDN).

📝 Syntax

General form of Document.querySelectorAll (MDN):

querySelectorAll(selectors)

Parameters

• selectors — a string containing one or more selectors to match. Must be valid CSS; otherwise a SyntaxError is thrown (MDN). Escape class/id values that are not valid CSS identifiers with CSS.escape() (MDN).

Return value

A non-live NodeList with one Element per match, or an empty NodeList when nothing matches (MDN). Elements are in document order (MDN).

Exceptions

• SyntaxError DOMException — thrown if the selector syntax is invalid (MDN).

Common beginner patterns

document.querySelectorAll("p");
document.querySelectorAll("div.note, div.alert");
document.querySelectorAll("iframe[data-src]");

const items = document.querySelectorAll(".card");
items.forEach((el) => {
  el.classList.add("is-ready");
});

⚖️ querySelectorAll vs querySelector vs getElementsByClassName

Examples Gallery

Examples follow MDN Document: querySelectorAll() and practical beginner patterns.

const matches = document.querySelectorAll("p");
console.log("paragraph count:", matches.length);
console.log("first text:", matches[0] ? matches[0].textContent : "(none)");

paragraph count: 2
first text: Hello

const matches = document.querySelectorAll("div.note, div.alert");
console.log(
  Array.from(matches).map((el) => el.className).join(", ")
);

note, alert, note

const matches = document.querySelectorAll("iframe[data-src]");
console.log("lazy iframes:", matches.length);
matches.forEach((frame) => {
  console.log(frame.getAttribute("data-src"));
});

lazy iframes: 2
video.mp4
map.html

const highlightedItems = document.querySelectorAll(".highlighted");

highlightedItems.forEach((item) => {
  item.classList.add("processed");
});

console.log("processed:", highlightedItems.length);

processed: 3
(each .highlighted gains class "processed")

const first = document.querySelector(".card");
const all = document.querySelectorAll(".card");

console.log("first tag:", first ? first.tagName : "null");
console.log("all length:", all.length);
console.log("same first node:", first === all[0]);

first tag: DIV
all length: 2
same first node: true

🚀 Common Use Cases

• Bulk UI updates — add a class to every .card or button.
• Mixed selector groups — div.note, div.alert in one call (MDN).
• Attribute filters — iframe[data-src], li[data-active='1'] (MDN).
• Scoped searches — find a container, then call Element.querySelectorAll() inside it (MDN).
• Snapshot lists — static NodeList is safe to iterate while mutating the DOM.
• Need only one? — prefer querySelector() (MDN).

📝 Notes

• MDN: Baseline Widely available since July 2015.
• Not Deprecated, Experimental, or Non-standard.
• MDN: returns a static NodeList — not live.
• MDN: CSS pseudo-elements always produce an empty list.
• MDN: escape class/id values that are not valid CSS identifiers.
• Related: querySelector(), Element.querySelectorAll(), getElementsByClassName().

💡 Best Practices