JavaScript Document querySelector() Method

Beginner
5 min read
Updated: Nov 2026
3 examples
Method
Decorative image with the word QUERYSELECTOR

Definition

document.querySelector(selectors) returns the first Element in the document that matches a CSS selector (or group of selectors). If nothing matches, it returns null. Matching walks the tree in document order (depth-first).

Pass the required arguments shown below. Check return values and browser support before you rely on the result.

Syntax

Call document.querySelector. Start with this line.

JavaScript
document.querySelector(selectors)
CallWhat it does
document.querySelector(selectors)Primary signature.
document.querySelector(...)Call with the arguments your case needs.

Built into the browser. Call querySelector(...) on document — no import required.

Library declarations
JavaScript
document.querySelector(selectors)

Parameters

ParameterDescription
selectorsRequired. Valid CSS selector string

Return Value

Return ValueDescription
*First matching Element, or null

JavaScript Examples

Example 1 — First Element with a Class

MDN-style: return the first element that has class myclass.

JavaScript
const el = document.querySelector(".myclass");
console.log(el ? el.textContent : null);
// first .myclass text, or null
Try It Yourself

How It Works

  1. Use a class selector. ".myclass" means “element with that class”.
  2. Take the first match. Later elements with the same class are ignored.
  3. Read safely. Check el before using textContent.
  4. Same idea for ids. "#id" works too; prefer getElementById for plain ids.

Example 2 — Nested Tag + Attribute Selector

Combine a container and an attribute to pinpoint one control.

JavaScript
const login = document.querySelector(
  "div.user-panel input[name='login']"
);

console.log(login ? login.value : null);
// value of that input, or null
Try It Yourself

How It Works

  1. Start at a container. div.user-panel narrows the search.
  2. Add a descendant. A space means “inside that div”.
  3. Match an attribute. input[name='login'] picks the named field.
  4. Still only the first. If several match, you get the earliest in the document.

Example 3 — Handle null When Nothing Matches

No match returns null — check before you touch the element.

JavaScript
const el = document.querySelector("#does-not-exist");

if (el === null) {
  console.log("not found");
} else {
  console.log(el.tagName);
}
Try It Yourself

How It Works

  1. Run the query. A missing id does not throw — it returns null.
  2. Compare to null. Avoid reading properties on a missing node.
  3. Branch clearly. Log a message or create the element if needed.
  4. Contrast with bad CSS. An invalid selector throws SyntaxError, which is different from “not found”.
Compatibility

Browser Support

Document.querySelector() is a browser DOM API marked Baseline Widely available on MDN (across browsers since July 2015).

✓ Baseline Widely available

Document.querySelector()

First Element matching a CSS selector — everyday DOM lookup for modern and legacy browsers.

Baseline Widely available
Google Chrome 1+
Yes
Microsoft Edge 12+
Yes
Mozilla Firefox 3.5+
Yes
Apple Safari 3.1+
Yes
Opera 10+
Yes
Internet Explorer 9+ (8 partial)
Yes
querySelector() Excellent in browsers

Bottom line: Safe for virtually all browsers you ship to. See the MDN Document.querySelector() reference.

Frequently Asked Questions

It returns the first Element in the document that matches a CSS selector (or group of selectors). If nothing matches, it returns null.
No. MDN marks Document.querySelector() as Baseline Widely available (across browsers since July 2015). It is not Deprecated, Experimental, or Non-standard.
The method returns null. Always check for null before reading properties like textContent or className.
A SyntaxError DOMException is thrown if the selectors string is not valid CSS.
querySelector() returns the first matching Element (or null). querySelectorAll() returns a static NodeList of all matches. Use querySelectorAll when you need every match.
When you have a unique, simple id and want the classic fast path. Use querySelector when you need classes, attributes, combinators, or :not() — and escape special characters in ids with CSS.escape().

Next: querySelectorAll()

Learn how to collect every element that matches a CSS selector.

querySelectorAll() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

18 people found this page helpful

JavaScript Document queryCommandSupported() Method JavaScript Document querySelectorAll() Method