--- 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"><div id="foo\bar"></div> <div id="foo:bar"></div> <script> 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') // 첫 번째 <div> document.querySelector('#foo:bar') // 일치하는 요소 없음 document.querySelector('#foo\\:bar') // 두 번째 <div> </script> </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><div class="user-panel main"></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>