Document: querySelector() method

selectors

A string containing one or more selectors to match. This string must be a valid CSS selector string; if it isn't, a SyntaxError exception is thrown.

Note that the HTML specification does not require attribute values to be valid CSS identifiers. If a class or id attribute value is not a valid CSS identifier, then you must escape it before using it in a selector, either by calling CSS.escape() on the value, or using one of the techniques described in Escaping characters. See Escaping attribute values for an example.

An Element object representing the first element in the document that matches the specified set of CSS selectors, or null is returned if there are no matches.

If you need a list of all elements matching the specified selectors, you should use querySelectorAll() instead.

SyntaxError DOMException

Thrown if the syntax of the specified selectors is invalid.

In this example, the first element in the document with the class myclass is returned:

const el = document.querySelector(".myclass");

Selectors can also be really powerful, as demonstrated in the following example. Here, the first <input> element with the name "login" (<input name="login"/>) located inside a <div> whose class is "user-panel main" (<div class="user-panel main">) in the document is returned:

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

As all CSS selector strings are valid, you can also negate selectors:

const el = document.querySelector(
  "div.user-panel:not(.main) input[name='login']",
);

This will select an input with a parent div with the user-panel class but not the main class.

This example shows that if an HTML document contains an id which is not a valid CSS identifier, then we must escape the attribute value before using it in querySelector().

HTML

In the following code, a <div> element has an id of "this?element", which is not a valid CSS identifier, because the "?" character is not allowed in CSS identifiers.

We also have three buttons, and a <pre> element for logging errors.

<div id="this?element"></div>

<button id="no-escape">No escape</button>
<button id="css-escape">CSS.escape()</button>
<button id="manual-escape">Manual escape</button>

<pre id="log"></pre>

CSS

div {
  background-color: blue;
  margin: 1rem 0;
  height: 100px;
  width: 200px;
}

JavaScript

All three buttons, when clicked, try to select the <div>, and then set its background color to a random value.

• The first button uses the "this?element" value directly.
• The second button escapes the value using CSS.escape().
• The third button explicitly escapes the "?" character using a backslash. Note that we must also escape the backslash itself, using another backslash, like: "\\?".

const log = document.querySelector("#log");

function random(number) {
  return Math.floor(Math.random() * number);
}

function setBackgroundColor(id) {
  log.textContent = "";

  try {
    const element = document.querySelector(`#${id}`);
    const randomColor = `rgb(${random(255)} ${random(255)} ${random(255)})`;
    element.style.backgroundColor = randomColor;
  } catch (e) {
    log.textContent = e;
  }
}

document.querySelector("#no-escape").addEventListener("click", () => {
  setBackgroundColor("this?element");
});

document.querySelector("#css-escape").addEventListener("click", () => {
  setBackgroundColor(CSS.escape("this?element"));
});

document.querySelector("#manual-escape").addEventListener("click", () => {
  setBackgroundColor("this\\?element");
});

Result

Clicking the first button gives an error, while the second and third buttons work properly.

• Locating DOM elements using selectors
• Element.querySelector()
• Document.querySelectorAll()
• Element.querySelectorAll()