JavaScript метод Element.querySelector()

Определение и применение

JavaScript метод querySelector() объекта Element возвращает первый элемент, соответствующий указанной группе селекторов, который является потомком элемента на котором был вызван метод. Если совпадений не найдено, то возвращается значение null.

Этот метод так же реализован как Document.querySelector(), DocumentFragment.querySelector() и ParentNode.querySelector().

Если вам необходим первый элемент в документе, который соответствует указанному селектору или селекторам, то используйте для этого метод querySelector() объекта Document.

Для того, чтобы возвратить статический (не живой) объект NodeList, представляющий список элементов, соответствующих указанной группе селекторов, которые являются потомками элемента, на котором был вызван метод, вы можете воспользоваться методом querySelectorAll().

Поддержка браузерами

Спецификация: dom.spec.whatwg

✓Поддерживается во всех основных браузерах с 2015 года.

Показать браузеры

ВсеКомпьютерыМобильные

Совместимостьapi.Element.querySelector

Возможность	Компьютеры					Мобильные
	ChromeChrome	EdgeEdge	FirefoxFirefox	OperaOpera	SafariSafari	Chrome AndroidChromeAndroid	Firefox for AndroidFirefoxAndroid	Opera AndroidOperaAndroid	Safari on iOSSafariiOS	Samsung BrowserSamsungAndroid	WebView AndroidWebViewAndroid	WebView on iOSWebViewiOS
querySelector	✓1	✓12	✓3.5	✓10	✓3.1	✓18	✓4	✓10.1	✓2	✓1.0	✓4.4	✓2

✓поддерживается◐с ограниченияминет поддержки?нет данных≤31 — не позднее версии 31

JavaScript синтаксис

const element = baseElement.querySelector(selectors);

Спецификация

DOM Standard.

Значения параметров

Исключения

Для значения id, включаемого в селектор, используйте CSS.escape(id): допустимый HTML-идентификатор не обязательно допустим в CSS без экранирования. Неверный синтаксис селектора вызывает SyntaxError.

Пример использования

Поиск первого пункта списка внутри блока

Нажмите ▶, затем Click me: первый пункт списка внутри div станет оранжево-красным. Замените селектор 'li' на 'li:last-child' и сравните.

index.html

HTML

<button data-migration-click-0="">Click me</button>
<div>
  <ul>
    <li>1</li>
    <li>2</li>
    <li>3</li>
  </ul>
</div>

main.js

JavaScript

function myFunc() {
    const myDiv = document.body.querySelector('div'),
        firstLi = myDiv.querySelector('li')

    firstLi.style.color = 'orangered'
}

// Обработчики кнопок перенесены из HTML для запуска с CSP без inline-скриптов.
document.querySelector('[data-migration-click-0]').addEventListener('click', function () {
    myFunc()
})
document.querySelector('[data-migration-click-0]').removeAttribute('data-migration-click-0')

В этом примере с использованием метода addEventListener() при нажатии на кнопку (HTML элемент <button>) вызываем функцию myFunc(), которая с использованием JavaScript метода querySelector() выбирает первый элемент <div> внутри элемента <body>, затем с помощью этого же метода осуществляет поиск внутри выбранного элемента <div>, и находит внутри него первый элемент <li>. После этого устанавливает ему определенный цвет текста.

Границы поиска и экранирование id

Добавьте вложенный абзац. Сравните p и :scope > p; идентификатор с двоеточием требует CSS.escape(). Предок в селекторе может находиться вне выбранного элемента.

index.html

HTML

<section id="catalog">
  <p id="item:1">Первый товар</p>
  <div><p>Вложенный товар</p></div>
</section>
<pre id="result"></pre>

main.js

JavaScript

const catalog = document.querySelector('#catalog')
const id = 'item:1'
const found = catalog.querySelector('#' + CSS.escape(id))
document.querySelector('#result').textContent = [
    'Экранированный id: ' + found.textContent,
    'Все потомки p: ' + catalog.querySelectorAll('p').length,
    'Только прямые дети: ' + catalog.querySelectorAll(':scope > p').length,
    'Селектор с псевдоэлементом: ' + catalog.querySelectorAll('p, ::before').length,
    'Предок вне области поиска: ' + catalog.querySelectorAll('body p').length,
].join('\n')