index.html

---
title: Element.querySelector()
slug: Web/API/Element/querySelector
tags:
  - API
  - CSS
  - CSS Selectors
  - DOM
  - Element
  - Elements
  - Finding Elements
  - Locating Elements
  - Method
  - Reference
  - Searching Elements
  - Selecting Elements
  - Selectors
  - querySelector
browser-compat: api.Element.querySelector
---
<div>{{APIRef("DOM")}}</div>

<p>The <code><strong>querySelector()</strong></code> method of the {{domxref("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.</p>

<h2 id="Syntax">Syntax</h2>

<pre class="brush: js"><var>element</var> = <em>baseElement</em>.querySelector(<em>selector</em>s);
</pre>

<h3 id="Parameters">Parameters</h3>

<dl>
  <dt><code>selectors</code></dt>
  <dd>A group of <a
      href="/en-US/docs/Learn/CSS/Building_blocks/Selectors">selectors</a> to match
    the descendant elements of the {{domxref("Element")}} <code>baseElement</code>
    against; this must be valid CSS syntax, or a <code>SyntaxError</code> exception will
    occur. The first element found which matches this group of selectors is returned.</dd>
</dl>

<h3 id="Return_value">Return value</h3>

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

<p>If no matches are found, the returned value is <code>null</code>.</p>

<h3 id="Exceptions">Exceptions</h3>

<dl>
  <dt><code>SyntaxError</code></dt>
  <dd>The specified <code>selectors</code> are invalid.</dd>
</dl>

<h2 id="Examples">Examples</h2>

<p>Let's consider a few examples.</p>

<h3 id="Find_a_specific_element_with_specific_values_of_an_attribute">Find a specific
  element with specific values of an attribute</h3>

<p>In this first example, the first {{HTMLElement("style")}} element which either has no
  type or has type "text/css" in the HTML document body is returned:</p>

<pre class="brush:js">var el = document.body.querySelector("style[type='text/css'], style:not([type])");
</pre>

<h3 id="Get_direct_descendants_using_the_scope_pseudo-class">Get direct descendants using the :scope pseudo-class</h3>

<p>This example uses the {{cssxref(":scope")}} pseudo-class to retrieve direct children of the <code>parentElement</code> element.</p>

<h4 id="HTML">HTML</h4>
<pre class="brush: html">&lt;div&gt;
  &lt;h6&gt;Page Title&lt;/h6&gt;
  &lt;div id="parent"&gt;
    &lt;span&gt;Love is Kind.&lt;/span&gt;
    &lt;span&gt;
      &lt;span&gt;Love is Patient.&lt;/span&gt;
    &lt;/span&gt;
    &lt;span&gt;
      &lt;span&gt;Love is Selfless.&lt;/span&gt;
    &lt;/span&gt;
  &lt;/div&gt;
&lt;/div&gt;
</pre>

<h4 id="CSS">CSS</h4>
<pre class="brush: css">
  span {
    display:block;
    margin-bottom: 5px;
  }
  .red span {
    background-color: red;
    padding:5px;
  }
</pre>

<h4 id="Javascript">JavaScript</h4>
<pre class="brush: js">
  const parentElement = document.querySelector('#parent');
  let allChildren = parentElement.querySelectorAll(":scope > span");
  allChildren.forEach(item => item.classList.add("red"));
</pre>

<h4 id="result">Result</h4>
<p>{{ EmbedLiveSample('Get_direct_descendants_using_the_scope_pseudo-class', 600, 160) }}</p>

<h3 id="The_entire_hierarchy_counts">The entire hierarchy counts</h3>

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

<h4 id="HTML">HTML</h4>

<pre class="brush: html">&lt;div&gt;
  &lt;h5&gt;Original content&lt;/h5&gt;
  &lt;p&gt;
    inside paragraph
    &lt;span&gt;inside span&lt;/span&gt;
    inside paragraph
  &lt;/p&gt;
&lt;/div&gt;
&lt;div&gt;
  &lt;h5&gt;Output&lt;/h5&gt;
  &lt;div id="output"&gt;&lt;/div&gt;
&lt;/div&gt;</pre>

<h4 id="JavaScript">JavaScript</h4>

<pre class="brush: js">var baseElement = document.querySelector("p");
document.getElementById("output").innerHTML =
  (baseElement.querySelector("div span").innerHTML);</pre>

<h4 id="Result">Result</h4>

<p>The result looks like this:</p>

<p>{{ EmbedLiveSample('The_entire_hierarchy_counts', 600, 160) }}</p>

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

<h3 id="More_examples">More examples</h3>

<p>See {{domxref("Document.querySelector()")}} for additional examples of the proper
  format for the <code>selectors</code>.</p>

<h2 id="Specifications">Specifications</h2>

{{Specifications}}

<h2 id="Browser_compatibility">Browser compatibility</h2>

<p>{{Compat}}</p>

<h2 id="See_also">See also</h2>

<ul>
  <li><a
      href="/en-US/docs/Web/API/Document_object_model/Locating_DOM_elements_using_selectors">Locating
      DOM elements using selectors</a></li>
  <li><a href="/en-US/docs/Web/CSS/Attribute_selectors">Attribute selectors</a> in the CSS
    Guide</li>
  <li><a href="/en-US/docs/Learn/CSS/Building_blocks/Selectors/Attribute_selectors">Attribute
      selectors</a> in the MDN Learning Area</li>
  <li>{{domxref("Element.querySelectorAll()")}}</li>
  <li>{{domxref("Document.querySelector()")}} and
    {{domxref("Document.querySelectorAll()")}}</li>
  <li>{{domxref("DocumentFragment.querySelector()")}} and
    {{domxref("DocumentFragment.querySelectorAll()")}}</li>
  <li>Other methods that take selectors: {{domxref("element.closest()")}} and
    {{domxref("element.matches()")}}.</li>
</ul>