querySelector() is a JavaScript DOM method that returns the first element matching a CSS selector. It is one of the most common ways to select elements before changing text, styles, attributes, classes, or event handlers.
Use document.querySelector() when searching the whole page. Use element.querySelector() when you want to search only inside a specific parent element. If you need every matching element, use querySelectorAll() instead.
Environment: Node.js v20.18.2. After each runnable snippet, the following paragraph states the expected console output (order and values).
JavaScript querySelector Syntax
const element = document.querySelector("selector");The selector is a CSS selector string. If a matching element exists, querySelector() returns the first matching Element. If no element matches, it returns null.
A simple helper test used for this article:
function firstSelector(selectors) {
return selectors[0];
}
console.log("queryselector-first:", firstSelector(["button.primary", "button.secondary"]));You should see one line logging queryselector-first: button.primary.
This mirrors the key behavior to remember: querySelector() returns the first match, not every match.
Method 1: Select an Element by ID
Use #id to select an element by ID.
<h1 id="title">Dashboard</h1>
<script>
const title = document.querySelector("#title");
console.log(title.textContent);
</script>In a real browser you should see one console line logging Dashboard.
For a simple ID lookup, getElementById() is also valid. querySelector() is more flexible because it accepts the same CSS selector patterns used for classes, attributes, and combinations.
Method 2: Select an Element by Class
Use .className to select the first element with a class.
<button class="primary">Save</button>
<button class="primary">Publish</button>
<script>
const button = document.querySelector(".primary");
console.log(button.textContent);
</script>You should see one line logging Save.
Only the first matching element is returned. For all matching buttons, use querySelectorAll(".primary").
Method 3: Select Nested Elements with CSS Selectors
querySelector() supports complex CSS selectors.
const email = document.querySelector("form.signup input[name='email']");This selects the first input with name="email" inside a form with class signup. Complex selectors are useful when the page has repeated components and you need a specific element inside one section.
Method 4: Use querySelectorAll for Multiple Elements
Use querySelectorAll() when you need every matching element.
const buttons = document.querySelectorAll("button.primary");
buttons.forEach((button) => {
button.disabled = true;
});querySelectorAll() returns a static NodeList, not a single element. You can loop through it with forEach() in modern browsers.
Method 5: Check for null Before Updating an Element
querySelector() returns null when no element matches. Always check the result before using element properties.
const message = document.querySelector(".message");
if (message) {
message.textContent = "Saved successfully";
}Without the null check, code such as message.textContent = ... throws an error when .message does not exist.
Method 6: Avoid Invalid Selector Errors
An invalid CSS selector throws a SyntaxError. This often happens when dynamic IDs or class names contain characters that need escaping.
const id = "user:42";
const element = document.querySelector("#" + CSS.escape(id));Use CSS.escape() when user-generated or external values become part of a selector.
Common Questions About querySelector in JavaScript
What does querySelector return?
It returns the first matching Element, or null when no element matches the selector.
What is the difference between querySelector and querySelectorAll?
querySelector() returns one element: the first match. querySelectorAll() returns a NodeList containing all matching elements.
Can querySelector use CSS selectors?
Yes. It accepts valid CSS selectors such as IDs, classes, attributes, descendants, child selectors, and grouped selectors.
Summary
document.querySelector() is the standard JavaScript method for selecting the first DOM element that matches a CSS selector. Use it for single-element updates, null-check the result before changing the DOM, and switch to querySelectorAll() when you need multiple matches. For dynamic selectors, escape unsafe values so invalid characters do not break the selector.
