JavaScriptDomBeginner

document.querySelector()

Selects the first DOM element matching a CSS selector (or null).

Review the syntaxStudy the examplesOpen the coding app
document.querySelector(cssSelector)
Open Coding Reference

This static page keeps the syntax and examples indexed for search, while the coding app handles interactive exploration and saved references.

What it does

Overview

Selects the first DOM element matching a CSS selector (or null).

document.querySelector() returns the first Element within the document that matches the specified CSS selector or group of selectors. If no matches are found, it returns null. The method performs a depth-first pre-order traversal of the document's nodes starting with the first element in the document's markup and proceeding through sequential nodes by order of child nodes. While extremely versatile due to its support for complex CSS3 selectors, it is computationally more expensive than getElementById() or getElementsByClassName() because the selector engine must parse the string and traverse the DOM. For optimal performance in tight loops, specialized methods are preferred. Note that querySelector() cannot select pseudo-elements like ::before or ::after, and it will throw a SyntaxError if the provided selector string is invalid.

Quick reference

Syntax

document.querySelector(cssSelector)

Inputs

Parameters

cssSelectorstring · CSS selector like '.btn' or '#title'.

See it in practice

Examples

1

Selecting by Class and Attribute

var activeUser = document.querySelector('.user-item[data-status="active"]');
console.log(activeUser ? activeUser.textContent : 'No active user found');
Output:
"John Doe" (assuming match exists)

Selects the first element with the class 'user-item' that also has a data-status attribute equal to 'active'.

2

Selecting the First Match in a List

var firstList = document.querySelector('ul > li:first-child');
if (firstList) {
  firstList.style.color = 'red';
  console.log('Styled the first list item');
}
Output:
"Styled the first list item"

Demonstrates using CSS pseudo-classes to target specific structural elements. Only the first match in the entire document is returned.

3

Safe Element Access

var btn = document.querySelector('#submit-btn');
if (btn) {
  btn.addEventListener('click', function() {
    console.log('Clicked!');
  });
} else {
  console.log('Button not found in the DOM');
}
Output:
"Button not found in the DOM" (if ID does not exist)

Shows the best practice of checking for null before attempting to access properties or methods on the returned value.

Debug faster

Common Errors

1

TypeError

Cause: Attempting to access properties (like .textContent or .style) on the result of querySelector() when no element matches the selector.

Fix: Always verify the return value is not null before accessing its properties.

document.querySelector('.non-existent').innerHTML = 'Hello';
2

DOMException (SyntaxError)

Cause: Passing a string that is not a valid CSS selector, such as a selector starting with a digit or containing unescaped special characters.

Fix: Ensure selectors follow CSS syntax rules. Use CSS.escape() for dynamic selectors containing special characters.

document.querySelector('123-id');

Runtime support

Compatibility

BrowserAll modern browsers, IE8+ (limited selectors)Modern DOM

Source: MDN Web Docs

Common questions

Frequently Asked Questions

Selects the first DOM element matching a CSS selector (or null).

cssSelector: CSS selector like '.btn' or '#title'.

TypeError: Always verify the return value is not null before accessing its properties. DOMException (SyntaxError): Ensure selectors follow CSS syntax rules. Use CSS.escape() for dynamic selectors containing special characters.