Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / JavaScript

Element.querySelector() and Element.querySelectorAll()

Find descendants of an element using CSS selectors. Choose between the first match and a static list of all matches.

Version: ECMAScript 2024 and the current web platform; runtime support varies

Syntax

element.querySelector(selectors)     // Element | null
element.querySelectorAll(selectors)  // static NodeList of Element objects

Element.querySelector/querySelectorAll refers to two instance methods. Each takes one string containing a CSS selector or a comma-separated list of CSS selectors. querySelector() returns the first matching element in document order, or null. querySelectorAll() returns a static NodeList of all matching elements in that same order: parents before descendants, earlier siblings before later ones. Selector-list order does not set priority, and each element appears at most once. With no matches, the list is empty (length === 0).

Only descendants of the element you call the method on can be returned, never that element itself. Matching can still depend on ancestors outside that subtree. :scope refers to the element you call the method on, so :scope > .item selects only its direct children with class item. Queries do not cross shadow DOM boundaries; to search inside one, call the method on an accessible ShadowRoot.

A static list keeps the membership and order it had at the time of the call. Changing a class, adding, removing, or moving an element does not update the list. Its entries still refer to the original Element objects, not copies. Run the query again for current results; use Array.from(list) if you need array methods.

An invalid selector string makes either method throw a DOMException named SyntaxError; that is different from getting no matches. CSS pseudo-elements such as ::before are not returned as DOM elements. When inserting a dynamic ID into a selector, use "#" + CSS.escape(id) to escape the CSS identifier, not a whole selector or HTML. These are web-platform DOM methods, not ECMAScript 2024 features. Check DOM and selector support in the target runtime.

Examples

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Element selector queries</title>
</head>
<body>
  <script>
    const frame = document.createElement("div");
    frame.className = "frame";
    const root = frame.appendChild(document.createElement("section"));
    const direct = root.appendChild(document.createElement("p"));
    const wrapper = root.appendChild(document.createElement("div"));
    const nested = wrapper.appendChild(document.createElement("p"));
    direct.className = nested.className = "item";
    direct.textContent = "A";
    nested.textContent = "B";

    const snapshot = root.querySelectorAll(".frame .item");
    console.log(root.querySelector(":scope > .item").textContent);
    console.log(snapshot.length);
    console.log(root.querySelectorAll(":scope > .item").length);

    nested.remove();
    console.log(`${snapshot.length} ${root.querySelectorAll(".frame .item").length}`);
  </script>
</body>
</html>

Result

A
2
1
2 1

Save the example as an HTML file, open it in a browser, and check the developer console for the output. `:scope > .item` finds only `A`, while `.frame .item` matches both paragraphs by using an ancestor outside `root`. After `B` is removed, the saved list still has two entries, but the new query returns one.

Related lessons

  • JavaScript · Lesson 30 · Advanced · Version: 4

Sources