document.querySelector() Since: Selectors API（2008）

// Search the entire document.
var element = document.querySelector("selector");

// Search within a specific HTML element.
var element = parentElement.querySelector("selector");

Returns the first matching HTML element (an Element object). Returns null if no matching element exists.

<div id="container">
	<p class="message">Hello</p>
	<p class="message">Goodbye</p>
</div>

// Select by ID.
var container = document.querySelector("#container");

// Only the first element with the matching class name is returned.
var msg = document.querySelector(".message");
console.log(msg.textContent); // Outputs "Hello".

// Select using a descendant selector.
var child = document.querySelector("#container .message");

Attempting to retrieve a non-existent element returns null. Operating on a null value causes an error, so always check before use.

// Try to select a non-existent element.
var el = document.querySelector("#nothing");
console.log(el); // Returns null.

// Operating on null causes an error.
el.innerHTML = "<p>Test</p>"; // TypeError: Cannot set properties of null

// Always check for null before operating on the element.
var el = document.querySelector("#btn");
if (el) {
	el.innerHTML = "<p>Click!</p>";
}

document.querySelector() is a method that retrieves an HTML element using CSS selector syntax. Unlike document.getElementById(), which searches only by ID, document.querySelector() accepts any CSS selector — including class names, attributes, and descendant selectors — making it a more flexible way to find elements.

However, even if multiple elements match the condition, only the first one is returned. To retrieve all matching elements, use document.querySelectorAll() instead.

document.querySelector() can be called not only on document but also on any HTML element. In that case, the search is limited to the descendants of that element.

<div id="section1">
	<p class="message">Message in section 1</p>
</div>
<div id="section2">
	<p class="message">Message in section 2</p>
</div>

// Search the entire document. Returns the first match found.
var msg = document.querySelector(".message");
console.log(msg.textContent); // Outputs "Message in section 1".

// Search within a specific element. The search is limited to its descendants.
var section2 = document.querySelector("#section2");
var msg2 = section2.querySelector(".message");
console.log(msg2.textContent); // Outputs "Message in section 2".

For a more in-depth explanation of document.querySelector(), see the tutorial article 'querySelector() — Getting Elements with CSS Selectors'.