querySelector() en JavaScript : trouver un élément avec un sélecteur CSS

Une feuille de style désigne déjà les éléments d'une page avec une syntaxe compacte : un point pour une classe, un dièse pour un identifiant, un espace pour la descendance.

Le DOM réutilise exactement cette syntaxe. Savoir écrire un sélecteur CSS suffit donc à retrouver n'importe quel élément depuis JavaScript.

Définition

querySelector reçoit un sélecteur CSS sous forme de chaîne et rend le premier élément du document qui lui correspond, dans l'ordre d'apparition du HTML. Si rien ne correspond, il rend null.

const titre = document.querySelector("h1");
const bouton = document.querySelector("#panier .valider");
const premierActif = document.querySelector("li.actif");

console.log(titre.textContent);
console.log(document.querySelector(".inexistant"));   // null

La méthode existe sur document et sur n'importe quel élément. N'importe quel sélecteur valide passe, y compris les pseudo-classes comme :first-child ou les sélecteurs d'attribut comme [data-id="12"].

querySelectorAll et sa liste figée

La variante querySelectorAll rend tous les éléments correspondants dans une NodeList. Cette liste est une photographie : elle ne change plus, même si la page change juste après.

const lignes = document.querySelectorAll("#panier li");

lignes.forEach((l) => l.classList.add("lu"));
console.log(lignes.length);

const textes = Array.from(lignes).map((l) => l.textContent);

Une NodeList possède forEach et length, mais ce n'est pas un Array (tableau) : ni map, ni filter, ni reduce. La convertir avec Array.from ou avec l'opérateur Spread (...) règle la question.

Chercher dans un sous-arbre

Appelée sur un élément, la méthode ne regarde que ses descendants. C'est la façon propre de travailler sur un composant sans risquer d'attraper un élément homonyme ailleurs dans la page.

const carte = document.querySelector(".carte-produit");
const prix = carte.querySelector(".prix");

console.log(prix.textContent);

Le null qui casse tout

Un sélecteur qui ne trouve rien ne lève aucune erreur. L'erreur arrive une ligne plus loin, sous la forme d'une TypeError annonçant qu'une propriété est lue sur null.

const element = document.querySelector(".absent");

console.log(element?.textContent);   // undefined, pas d'erreur
if (element) element.classList.add("actif");

Le Chaînage optionnel (?.) suffit pour une lecture. Dès qu'une suite d'instructions dépend de l'élément, une condition explicite reste plus lisible.

Questions fréquentes

La méthode lève immédiatement une erreur de syntaxe, ce qui distingue une faute de frappe dans la syntaxe CSS d'une recherche sans résultat. Un sélecteur mal écrit s'arrête net, un sélecteur correct qui ne trouve rien rend simplement null.

Pas à l'échelle d'une interface courante : les moteurs optimisent fortement ces recherches. Le vrai coût apparaît quand la même recherche est relancée dans une boucle ou à chaque mouvement de souris. Rangez le résultat dans une const et réutilisez-le.

Pour retrouver un élément par son identifiant, getElementById() reste marginalement plus rapide et exprime mieux l'intention. Pour tout le reste, la souplesse du sélecteur CSS l'emporte largement, et un code qui n'utilise qu'une seule méthode de recherche se lit plus facilement.