Document.querySelector()는 제공한 선택자 또는 선택자 뭉치와 일치하는 문서 내 첫 번째 Element를 반환합니다. 일치하는 요소가 없으면 null을 반환합니다.

참고: 탐색은 깊이우선(depth-first) 전위순회(pre-order)로, 시작점은 문서의 첫 번째 요소입니다.

구문

element = document.querySelector(selectors);

매개변수

selectors
하나 이상의 선택자를 포함한 DOMString. 유효한 CSS 선택자여야만 하며 아닐 경우 SYNTAX_ERR 예외가 발생합니다. Locating DOM elements using selectors를 참고해 선택자와 작성 방법을 더 알아보세요.

참고: CSS 표준 구문이 포함하는 문자가 아닌 경우 역슬래시로 이스케이프해야 합니다. JavaScript 또한 역슬래시로 이스케이프를 하기 때문에 특히 주의를 기울여야 합니다. 자세한 내용은 특수 문자 이스케이프 항목을 참고하세요.

반환값

제공한 CSS 선택자를 만족하는 첫 번째 Element 객체. 결과가 없다면 null.

선택자를 만족하는 모든 요소의 목록이 필요하다면 querySelectorAll()을 대신 사용하세요.

예외

SYNTAX_ERR
selectors의 구문이 유효하지 않음.

참고

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

CSS 의사 요소는 선택자 API가 명시한 대로 어떠한 요소도 반환하지 않습니다.

특수 문자 이스케이프

CSS 구문을 따르지 않는 selector나 ID와 매칭시키려면, 예를 들어 콜론(:)이나 공백이 포함된 경우, 반드시  백슬래시(\)를 이용하여 해당 문자를 escape해야 합니다. 백슬래시는 JavaScript의 escape 문자이기 때문에, 당신이 literal string을 입력하려고 한다면 반드시 두번 escape 해야 합니다. (한번은 Javascript string 에 사용하고, 또 다른 한 번은 querySelector에 사용됩니다.)

<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')    // Does not match anything
  document.querySelector('#foo\\:bar')  // 두 번째 <div>를 불러온다.
</script>

예제

클래스를 만족하는 첫 번째 요소 검색

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

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

좀 더 복잡한 선택자

선택자는 정말 강력할 수 있습니다. 아래 예제의 결과는 클래스가 "user-panel main"인 <div>(<div class="user-panel main">) 안의, 이름이 "login"인 <input> 중 첫 번째 요소입니다.

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

명세

명세 상태 비고
Selectors API Level 2
The definition of 'document.querySelector()' in that specification.
Obsolete  
Selectors API Level 1
The definition of 'document.querySelector()' in that specification.
Obsolete Initial definition

브라우저 호환성

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
Basic supportChrome Full support 1Edge Full support YesFirefox Full support 3.5IE Full support 8Opera Full support 10Safari Full support 3.2WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support YesOpera Android Full support 10Safari iOS Full support 3.2Samsung Internet Android ?

Legend

Full support  
Full support
Compatibility unknown  
Compatibility unknown

더 보기

문서 태그 및 공헌자

이 페이지의 공헌자: urty5656, daktwigim, DeadIntegral, imskojs
최종 변경자: urty5656,