정의 및 사용 방법

querySelector() 함수는
호출한 Document나 Element 객체 내에서 지정한 CSS 선택자와 일치하는 첫 번째 요소 객체를 반환합니다.

일치하는 요소가 없으면 null을 반환합니다.

기본 예제

JavaScript 
// 문서 내 첫 번째 클래스명이 ".item"인 요소 선택
const firstItem = document.querySelector(".item");

// 특정 요소 내에서 선택
const container = document.getElementById("container");
const nestedButton = container.querySelector("button.primary");

// 일치하는 요소가 없을 경우
const notExist = document.querySelector(".no-such-class"); // null 반환

구문

JavaScript 
// Document 객체(문서 전체)에서 호출
document.querySelector(selectors)

// Element 객체(특정 요소)에서 호출
element.querySelector(selectors)

매개변수

querySelector() 함수의 매개변수
selectors 선택하고자 하는 요소 객체입니다.
유효한 CSS 선택자 문자열로 지정해야 합니다. 지정하지 않으면 TypeError가 발생합니다.

반환 값

  • Document 객체(문서 전체)에서 호출했을 경우에는 문서 내에서 지정한 CSS 선택자와 일치하는 첫 번째 요소 객체를 반환합니다.
  • Element 객체(특정 요소)에서 호출했을 경우에는해당 특정 요소 내에서 지정한 CSS 선택자와 일치하는 첫 번째 요소 객체를 반환합니다.
  • 일치하는 요소가 없으면 null을 반환합니다.

참고하세요!
지정한 선택자와 일치하는 모든 요소의 목록이 필요한 경우 querySelectorAll() 함수를 사용하세요.

예제

querySelector() 함수의 사용법을 예제를 통해 살펴보겠습니다.

특정한 요소 내에서 요소 찾기

특정한 요소 내에서(예제의 경우 <div class="container">) 첫 번째 <p> 요소를 찾으려면 다음의 예제와 같이 작성할 수 있습니다.

HTML 
<div class="container">
    <p>자손 요소입니다.</p>
</div>
JavaScript 
let container = document.querySelector(".container"); // 특정한 요소 객체입니다.

let matche = container.querySelector("p"); // 특정한 요소 객체 내에서 요소 찾기
/* let matche = document.querySelector(".container p");와 동일한 반환값입니다. */

요소 스타일 변경하기

HTML 
<div id="my-element">이 요소의 스타일을 변경합니다.</div>
JavaScript 
const element = document.querySelector("#my-element");

element.style.backgroundColor = "lightblue";
element.style.color = "darkblue";

이 예제에서는 querySelector() 함수를 사용하여 문서 내에서 id가 "my-element"인 요소를 선택하고, 선택한 요소의 스타일을 변경합니다.

이벤트 리스너 추가하기

HTML 
<button id="my-button">클릭하세요</button>
JavaScript 
const button = document.querySelector("#my-button");

button.addEventListener("click", () => {
    alert("버튼이 클릭되었습니다!");
});

이 예제에서는 querySelector() 함수를 사용하여 문서 내에서 id가 "my-button"인 버튼 요소를 선택하고, 해당 버튼에 클릭 이벤트 리스너를 추가합니다. 버튼이 클릭될 때 메시지가 표시됩니다.

동적으로 내용 추가하기

HTML 
<ul id="my-list"></ul>
JavaScript 
const myList = document.querySelector("#my-list");
const items = ["항목 1", "항목 2", "항목 3"];
const itemsLength = items.length;

for (let i = 0; i < itemsLength; i++) {
    let listItem = document.createElement("li");
    listItem.textContent = items[i];
    myList.appendChild(listItem);
}

코드 부연설명
for 문은 특정 횟수나 범위만큼 반복하는 반복문입니다.

코드 부연설명
createElement() 함수는 새로운 HTML 요소를 생성해서 반환합니다.

코드 부연설명
appendChild() 함수는 노드를 특정 노드의 마지막 자식으로 추가합니다.

이 예제에서는 querySelector() 함수를 사용하여 문서 내에서 id가 "my-list"인 목록 요소를 선택하고, 자바스크립트를 사용하여 목록에 동적으로 항목을 추가합니다. 이것은 동적으로 콘텐츠를 생성하고 추가하는 데 사용되는 일반적인 패턴 중 하나입니다.

일치하는 요소가 없을 때 null을 반환

HTML 
<!DOCTYPE html>
<html lang="ko">
    <head>
        <title>querySelector() 예제</title>
    </head>
    <body>
        <div id="my-element">이 요소를 선택할 수 있습니다.</div>
        <script>
            const nonExistentElement = document.querySelector("#non-existent-element");
            
            if (nonExistentElement === null) {
              console.log("일치하는 요소가 없습니다.");
            } else {
              console.log("일치하는 요소를 찾았습니다.");
            }
        </script>
    </body>
</html>

이 예제에서는 문서 내에 id가 "non-existent-element"로 설정된 요소는 없으므로 querySelector()로 선택한 #non-existent-element 선택자는 일치하는 요소가 없어 null을 반환합니다. 그런 다음 자바스크립트에서 if...else 문을 사용하여 결과를 확인하고 콘솔에 메시지를 출력합니다. 결과는 "일치하는 요소가 없습니다."가 될 것입니다.

브라우저 호환성

querySelector() 함수의 브라우저 호환성
함수
데스크탑 Chrome
Chrome
데스크탑데스크탑 Edge
Edge
데스크탑 Firefox
Firefox
Safari
Safari
querySelector() 1 12 3.5 3.1

명세서

querySelector() 함수의 명세서 사양
명세서 사양
querySelector() DOM Standard
#ref-for-dom-parentnode-queryselector①

참고문헌

같이 보기