Element: querySelector() method
===============================

 The **`querySelector()`** method of the `Element`
 interface returns the first element that is a descendant of the element on which it is
 invoked that matches the specified group of selectors.

Syntax
------


```js
querySelector(selectors)
```

### Parameters

`selectors`

 A group of selectors to match
 the descendant elements of the `Element` `baseElement`
 against; this must be valid CSS syntax, or a `SyntaxError` exception will
 occur. The first element found which matches this group of selectors is returned.


### Return value

 The first descendant element of `baseElement` which matches the specified
 group of `selectors`. The entire hierarchy of elements is considered when
 matching, including those outside the set of elements including `baseElement`
 and its descendants; in other words, `selectors` is first applied to the
 whole document, not the `baseElement`, to generate an initial list of
 potential elements. The resulting elements are then examined to see if they are
 descendants of `baseElement`. The first match of those remaining elements is
 returned by the `querySelector()` method.

If no matches are found, the returned value is `null`.

### Exceptions

`SyntaxError` `DOMException`

Thrown if the specified `selectors` are invalid.

Examples
--------

Let's consider a few examples.

### Find a specific element with specific values of an attribute

 In this first example, the first `<style>` element which either has no
 type or has type "text/css" in the HTML document body is returned:


```js
const el = document.body.querySelector(
  "style[type='text/css'], style:not([type])",
);
```

### Get direct descendants using the :scope pseudo-class

This example uses the `:scope` pseudo-class to retrieve direct children of the `parentElement` element.

#### HTML


```html
<div>
  <h6>Page Title</h6>
  <div id="parent">
    <span>Love is Kind.</span>
    <span>
      <span>Love is Patient.</span>
    </span>
    <span>
      <span>Love is Selfless.</span>
    </span>
  </div>
</div>
```


#### CSS


```css
span {
  display: block;
  margin-bottom: 5px;
}
.red span {
  background-color: red;
  padding: 5px;
}
```


#### JavaScript


```js
const parentElement = document.querySelector("#parent");
let allChildren = parentElement.querySelectorAll(":scope > span");
allChildren.forEach((item) => item.classList.add("red"));
```


#### Result

### The entire hierarchy counts

 This example demonstrates that the hierarchy of the entire document is considered when
 applying `selectors`, so that levels outside the specified
 `baseElement` are still considered when locating matches.

#### HTML


```html
<div>
  <h5>Original content</h5>
  <p>
    inside paragraph
    <span>inside span</span>
    inside paragraph
  </p>
</div>
<div>
  <h5>Output</h5>
  <div id="output"></div>
</div>
```


#### JavaScript


```js
const baseElement = document.querySelector("p");
document.getElementById("output").innerHTML =
  baseElement.querySelector("div span").innerHTML;
```


#### Result

The result looks like this:

 Notice how the `"div span"` selector still successfully matches the
 `<span>` element, even though the `baseElement`'s child nodes
 do not include the `<div>` element (it is still part of the specified
 selector).

### More examples

 See `Document.querySelector()` for additional examples of the proper
 format for the `selectors`.

Specifications
--------------

| Specification |
| --- |
| DOM Standard # ref-for-dom-parentnode-queryselectorall① |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Locating DOM elements using selectors
* Attribute selectors in the CSS
 Guide
* Attribute selectors in the MDN Learning Area
* `Element.querySelectorAll()`
* `Document.querySelector()` and
 `Document.querySelectorAll()`
* `DocumentFragment.querySelector()` and
 `DocumentFragment.querySelectorAll()`
* Other methods that take selectors: `element.closest()` and
 `element.matches()`.