JavaScript querySelector() vs. querySelectorAll()

Key Differences

Both the querySelector() and querySelectorAll() functions are used to select element(s) in an HTML document. While they share this common purpose, there are several important differences between them.

Because the two function names are similar, many developers—especially those who have experience working with the DOM using jQuery—often confuse the two.

The querySelector() function returns only the first element that matches the specified CSS selector within the document or a specific element. In contrast, the querySelectorAll() function returns all matching elements.

In addition to this fundamental difference, the two functions also return different types of objects and are handled in distinctly different ways.

Comparison of the Two Functions

Both functions are used to select element(s) in an HTML document using CSS selectors. Below is a comparison of the two functions.

Comparison of the `querySelector()` and `querySelectorAll()` functions
Comparison Item	`querySelector()`	`querySelectorAll()`
Use Case	Selects the first element within the HTML document or a specific element that matches the specified CSS selector parameter	Selects all elements within the HTML document or a specific element that match the specified CSS selector parameter
Parameter	A valid CSS selector string	A valid CSS selector string
When matching elements exist	Returns the first matching element only	Returns all matching elements
Return value type	An element node	A list of `NodeList` objects in an array-like structure
When no matching elements exist	Returns `null`	Returns an empty `NodeList` object
Handling selected element(s)	You can directly apply properties or functions to the selected element node.	You can iterate over the `NodeList` object using the `forEach()` function, `for` loop, `for...of` loop, etc., and apply properties or functions to each element node.

Comparison of Handling Selected Element(s)

The key difference between querySelector() and querySelectorAll() lies in how the selected element(s) are handled.

The querySelector() function returns the first matching element, allowing you to directly apply properties or functions to that element node.
The querySelectorAll() function returns a NodeList object containing all matching elements. You need to iterate over this list using methods such as the forEach() function, a for loop, or a for...of loop to access each element node and apply properties or functions.

Consider the following examples:

JavaScript

// Example using querySelector()
const element = document.querySelector(".my-class"); // Returns the first matching element
element.textContent = "Element selected with querySelector()";

// Example using querySelectorAll()
const elements = document.querySelectorAll(".my-class"); // Returns all matching elements
elements.forEach((element, index) => { // Iteration is required
    element.textContent = `Element selected with querySelectorAll() ${index}`;
});

For further reading, refer to the following topics:

Conclusion and Recommendations

We have compared the querySelector() and querySelectorAll() functions and examined their differences. Here are the main considerations when choosing between them:

Use querySelector() when you need to select a single element, and use querySelectorAll() when selecting multiple elements.
When working with large DOM structures, querySelectorAll() may be more efficient. However, performance differences can be minimal, so make decisions based on your specific use case.

Finally, when writing code, consider the characteristics and caveats of the selected function. Use the browser console to verify results and debug when necessary.

Browser compatibility

Browser compatibility for JavaScript querySelector() and querySelectorAll() Functions
Method	Desktop Chrome	DesktopDesktop Edge	Desktop Firefox	Safari
`querySelector()`	1	12	3.5	3.1
`querySelectorAll()`	1	12	3.5	3.1

Specifications

Specification for JavaScript querySelector() and querySelectorAll() Functions
Specification
`querySelector()`	DOM Standard #ref-for-dom-parentnode-queryselector①
`querySelectorAll()`	DOM Standard #ref-for-dom-parentnode-queryselectorall①