El método querySelectorAll() de un Element devuelve una NodeList estática (no viva) que representa una lista de elementos del documento que coinciden con el grupo de selectores indicados.

Nota: Esto método se implementa en base al método querySelectorAll() del mixin ParentNode.

Sintaxis

elementList = parentNode.querySelectorAll(selectors);

Parámetros

selectors
Un DOMString que contiene uno o más selectores para buscar coincidencias. Esta cadena de texto debe ser una cadena CSS selector válida; si no lo es, se lanzará una excepción SyntaxError. Vea Locating DOM elements using selectors para más información acerca de utilizar selectores para identificar elementos. Se pueden especificar varios selectores separándolos utilizando comas.

Nota: Los caracteres que no son parte de la sintaxis estándar de CSS deben ser escapados utilizando el caracter de barra invertida. Dado que JavaScript también utiliza el escapado por retroceso, se debe tener especial cuidado al escribir cadenas de texto literales utilizando estos caracteres. Vea Escapando caracteres especiales para más información.

Valor devuelto

Una NodeList no viva que contenga un objeto Element para cada elemento que coincida con al menos uno de los selectores especificados o una NodeList vacía en caso de que no haya coincidencias.

Nota: Si los selectores indicados incluyen un pseudo-elemento CSS, la lista devuelta siempre estará vacía.

Excepciones

SyntaxError
La sintaxis de la cadena de texto selectors no es válida.

Ejemplos

Obteniendo una lista de coincidencias

Para obtener una NodeList de todos los elementos <p> en el documento:

var matches = document.querySelectorAll("p");

Este ejemplo devuelve una lista de todos los elementos <div> del documento con una clase "nota" o "alerta":

var matches = document.querySelectorAll("div.nota, div.alerta");

Aquí, se obtiene una lista de elementos <p> cuyo elemento padre inmediato es un div con la clase "highlighted" y que está ubicado dentro de un contenedor cuyo ID es "test".

var container = document.querySelector("#test");
var matches = container.querySelectorAll("div.highlighted > p");

Este ejemplo usa un selector de atributos para devolver una lista de elementos iframe en el documento que contienen un atributo llamado "data-src":

var matches = document.querySelectorAll("iframe[data-src]");

Aquí, un selector de atributo se utiliza para devolver una lista de los elementos de una lista cuyo ID es "userlist" que tiene un atributo "data-active" cuyo valor es "1":

var container = document.querySelector("#userlist");
var matches = container.querySelectorAll("li[data-active=1]");

Accediendo a las coincidencias

Una vez que se devuelve la NodeList de los elementos que coinciden, se puede examinar como cualquier array. Si el array está vacío (lo que significa que su propiedad length es 0), entonces es que no se encontraron coincidencias.

En cualquier caso, se puede simplemente utilizar la notación estándar de los arrays para acceder al contenido de la lista. Se puede usar cualquier sentencia de iteración, como por ejemplo:

var highlightedItems = userList.querySelectorAll(".highlighted");

highlightedItems.forEach(function(userItem) {
  deleteUser(userItem);
});

Notas de usuario

querySelectorAll() se comporta de forma diferente que la mayoría de librerías DOM de JavaScript, que pueden llevar a resultados inesperados.

HTML

Considere este HTML, con sus tres bloques anidados <div>.

<div class="outer">
  <div class="select">
    <div class="inner">
    </div>
  </div>
</div>

JavaScript

var select = document.querySelector('.select');
var inner = select.querySelectorAll('.outer .inner');
inner.length; // 1, not 0!

En este ejemplo, cuando se selecciona ".outer .inner" en el contexto el <div> con la clase "select", el elemento con la clase ".inner" todavía es encontrado, aun sabiendo que .outer no es descendiente del elemento base sobre el que se realiza la búsqueda (".select"). Por defecto, querySelectorAll() sólo verifica que el último elemento en el selector se encuentra dentro del rango de búsqueda.

La pseudo-clase :scope recupera el comportamiento esperado, encontrando coincidencias sólo en selectores descendientes del elemento base:

var select = document.querySelector('.select');
var inner = select.querySelectorAll(':scope .outer .inner');
inner.length; // 0

Especificaciones

Especificación Estado Comentario
DOM
La definición de 'ParentNode.querySelectorAll()' en esta especificación.
Living Standard Estándar vivo
Selectors API Level 2
La definición de 'ParentNode.querySelectorAll()' en esta especificación.
Obsolete Sin cambios
DOM4
La definición de 'ParentNode.querySelectorAll()' en esta especificación.
Obsolete Definición inicial
Selectors API Level 1
La definición de 'document.querySelector()' en esta especificación.
Obsolete Definición original

Compatibilidad en navegadores

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox for AndroidOpera for AndroidiOS SafariSamsung Internet
Soporte básicoChrome Soporte completo 1Edge Soporte completo SiFirefox Soporte completo 3.5IE Soporte completo 8Opera Soporte completo 10Safari Soporte completo 3.2WebView Android Soporte completo SiChrome Android Soporte completo SiEdge Mobile Soporte completo SiFirefox Android Soporte completo SiOpera Android Soporte completo 10Safari iOS Soporte completo SiSamsung Internet Android ?

Leyenda

Soporte completo  
Soporte completo
Compatibility unknown  
Compatibility unknown

Ver también

Etiquetas y colaboradores del documento

Colaboradores en esta página: AlePerez92, padrecedano, lfottaviano, joeljose
Última actualización por: AlePerez92,