---
title: Document.querySelector()
slug: Web/API/Document/querySelector
tags:
  - API
  - CSS Selectors
  - DOM
  - DOM Elements
  - Document
  - Method
  - Reference
  - Selectors
  - Web
translation_of: Web/API/Document/querySelector
---
<div>{{ApiRef("DOM")}}</div>

<p><strong><code>Document.querySelector()</code></strong>는 제공한 선택자 또는 선택자 뭉치와 일치하는 문서 내 첫 번째 {{domxref("Element")}}를 반환합니다. 일치하는 요소가 없으면 <code>null</code>을 반환합니다.</p>

<div class="note">
<p><strong>참고</strong>: 탐색은 깊이우선<sup>depth-first</sup> 전위<sup>pre-order</sup>순회로, 문서의 첫 번째 요소부터 시작해 자식 노드의 수를 기준으로 순회합니다.</p>
</div>

<h2 id="Syntax" name="Syntax">구문</h2>

<pre class="syntaxbox">document.querySelector(<var>selectors</var>);
</pre>

<h3 id="매개변수">매개변수</h3>

<dl>
 <dt><code>selectors</code></dt>
 <dd>하나 이상의 선택자를 포함한 {{domxref("DOMString")}}. 유효한 CSS 선택자여야만 하며 아닐 경우 <code>SYNTAX_ERR</code> 예외가 발생합니다. <a href="/ko/docs/Web/API/Document_object_model/Locating_DOM_elements_using_selectors">선택자로 DOM 요소 선택하기</a> 문서를 참고해 선택자와 선택자 작성 방법을 더 알아보세요.</dd>
</dl>

<div class="note">
<p><strong>참고</strong>: CSS 표준 구문이 포함하는 문자가 아닌 경우 역슬래시로 이스케이프해야 합니다. JavaScript 또한 역슬래시로 이스케이프를 하기 때문에 특히 주의를 기울여야 합니다. 자세한 내용은 {{anch("특수 문자 이스케이프")}} 항목을 참고하세요.</p>
</div>

<h3 id="반환값">반환값</h3>

<p>제공한 <a href="/ko/docs/Web/CSS/CSS_%EC%84%A0%ED%83%9D%EC%9E%90">CSS 선택자</a>를 만족하는 첫 번째 {{domxref("Element")}} 객체. 결과가 없다면 <code>null</code>.</p>

<p>선택자를 만족하는 모든 요소의 목록이 필요하다면 {{domxref("Document.querySelectorAll", "querySelectorAll()")}}을 대신 사용하세요.</p>

<h3 id="예외">예외</h3>

<dl>
 <dt><code>SYNTAX_ERR</code></dt>
 <dd><code>selectors</code>의 구문이 유효하지 않음.</dd>
</dl>

<h2 id="Notes" name="Notes">참고</h2>

<p>만약 <code>selector</code>가 ID 선택자인데, 해당 ID를 잘못 사용하여 문서 내에 여러 번 사용했으면 첫 번째로 그 ID를 사용한 요소를 반환합니다.</p>

<p><a href="/ko/docs/Web/CSS/Pseudo-elements">CSS 의사 요소</a>는 <a href="http://www.w3.org/TR/selectors-api/#grammar">선택자 API</a>가 명시한 대로 어떠한 요소도 반환하지 않습니다.</p>

<h3 id="특수_문자_이스케이프">특수 문자 이스케이프</h3>

<p>CSS 구문을 따르지 않는, 예컨대 콜론이나 공백을 포함한 선택자나 ID를 사용해야 하면 반드시  백슬래시("<code>\</code>")를 사용해 해당 문자를 이스케이프해야 합니다. 백슬래시는 JavaScript의 이스케이프 문자이기 때문에, 백슬래시를 문자로 입력하려면 반드시 두 번 이스케이프해야 합니다. 한 번은 JavaScript 문자열에 필요하고, 또 다른 한 번은 <code>querySelector()</code>에 필요합니다.</p>

<pre class="brush: html">&lt;div id="foo\bar"&gt;&lt;/div&gt;
&lt;div id="foo:bar"&gt;&lt;/div&gt;

&lt;script&gt;
  console.log('#foo\bar')             // "#fooar" ('\b'는 백스페이스 컨트롤 문자)
  document.querySelector('#foo\bar')  // 일치하는 요소 없음

  console.log('#foo\\bar')            // "#foo\bar"
  console.log('#foo\\\\bar')          // "#foo\\bar"
  document.querySelector('#foo\\bar') // 첫 번째 &lt;div&gt;

  document.querySelector('#foo:bar')   // 일치하는 요소 없음
  document.querySelector('#foo\\:bar') // 두 번째 &lt;div&gt;
&lt;/script&gt;
</pre>

<h2 id="Examples" name="Examples">예제</h2>

<h3 id="클래스를_만족하는_첫_번째_요소_검색">클래스를 만족하는 첫 번째 요소 검색</h3>

<p>아래 예제는 문서에서 "<code>myclass</code>"라는 클래스를 사용하는 첫 번째 요소를 반환합니다.</p>

<pre class="brush: js">var el = document.querySelector(".myclass");
</pre>

<h3 id="좀_더_복잡한_선택자">좀 더 복잡한 선택자</h3>

<p>아래 예제처럼 정말 강력한 선택자도 사용할 수 있습니다. 예제의 결과는 클래스가 "<code>user-panel main</code>"인 {{HTMLElement("div")}}(<code>&lt;div class="user-panel main"&gt;</code>) 안의, 이름이 "<code>login</code>"인 {{HTMLElement("input")}} 중 첫 번째 요소입니다.</p>

<pre class="brush: js">var el = document.querySelector("div.user-panel.main input[name=login]");
</pre>

<h2 id="Specifications" name="Specifications">명세</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">명세</th>
   <th scope="col">상태</th>
   <th scope="col">비고</th>
  </tr>
  <tr>
   <td>{{SpecName("Selectors API Level 2", "#interface-definitions", "document.querySelector()")}}</td>
   <td>{{Spec2("Selectors API Level 2")}}</td>
   <td> </td>
  </tr>
  <tr>
   <td>{{SpecName("Selectors API Level 1", "#interface-definitions", "document.querySelector()")}}</td>
   <td>{{Spec2("Selectors API Level 1")}}</td>
   <td>Initial definition</td>
  </tr>
 </tbody>
</table>

<h2 id="Browser_Compatibility" name="Browser_Compatibility">브라우저 호환성</h2>



<div>{{Compat("api.Document.querySelector")}}</div>

<h2 id="See_also" name="See_also">더 보기</h2>

<ul>
 <li><a href="/ko/docs/Web/API/Document_object_model/Locating_DOM_elements_using_selectors">선택자로 DOM 요소 선택하기</a></li>
 <li>{{domxref("element.querySelector()")}}</li>
 <li>{{domxref("document.querySelectorAll()")}}</li>
 <li>{{domxref("element.querySelectorAll()")}}</li>
</ul>