La méthode querySelector() de l'interface Document retourne le premier Element dans le document correspondant au sélecteur - ou groupe de sélecteurs - spécifié(s), ou null si aucune correspondance n'est trouvée.

Note : La correspondance est effectuée en utilisant le parcours pré-ordonné profondeur-d'abord des nœuds du document, en partant du premier élément dans le balisage du document et en itérant à travers les nœuds en séquence, par ordre du compte de nœuds enfants.

Syntaxe

element = document.querySelector(sélecteurs);

Paramètres

selectors (sélecteurs)
une  DOMString ( chaîne de caractères) qui contient un ou plusieurs sélecteurs à comparer. La chaîne doit être composée de sélecteurs CSS valides ; sinon une exception SYNTAX_ERR est lancée. Voir Localisation des éléments DOM avec les sélecteurs pour plus d'informations sur les sélecteurs et leur gestion.

Note : les caractères qui n'appartiennent pas à la syntaxe standard CSS doivent être échappés par un antislash ("\"). Puisque JavaScript utilise aussi cette barre pour l'échappement, une attention particulière est nécessaire quand des chaînes comprennent ces caractères. Voir Caractère spécial d'échappement pour plus d'informations.

Valeur retournée

Un objet Element représentant le premier élément dans le document qui corresponde au jeu de sélecteurs CSS spécifié.

Si vous avez besoin d'une liste de tous les éléments correspondant aux sélecteurs spécifiés, vous devez utiliser querySelectorAll() à la place.

Exception

SYNTAX_ERR
La syntaxe des sélecteurs spécifiés est invalide.

Notes d'utilisation

Si le sélecteur correspond à un ID et que cet ID est utilisé de façon erronée plusieurs fois dans le document, le premier élément en correspondance est retourné.

Les pseudo-éléments CSS ne retourneront jamais aucun élément, comme spécifié dans l'API des sélecteurs (en).

Caractère spécial d'échappement

Pour faire correspondre un ID (identifiant) ou un sélecteur qui ne respecte pas la syntaxe CSS (en utilisant un point virgule ou un espace par exemple), vous devez échapper le caractère avec un antislash (\). Comme l'antislash est un caractère d'échappement en JavaScript, si vous entrez une chaîne de caractères littérale, vous devez donc l'échapper deux fois (une pour la chaîne de caractères JavaScript et une autre fois pour querySelector) :

<div id="machin\bidule"></div>
<div id="machin:bidule"></div>

<script>
  console.log('#machin\bidule')               // "#machinidule" (\b est le caractère de contrôle retour arrière)
  document.querySelector('#machin\bidule')    // ne correspond à rien

  console.log('#machin\\bidule')              // "#machin\bidule"
  console.log('#machin\\\\bidule')            // "#machin\\bidule"
  document.querySelector('#machin\\\\bidule') // correspond au premier div

  document.querySelector('#machin:bidule')    // ne correspond à rien
  document.querySelector('#machin\\:bidule')  // correspond au second div
</script>

Exemples

Trouver le premier élément correspondant à une classe

Dans cet exemple, le premier élément dans le document qui contient la classe "maclasse" est retourné :

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

Un sélecteur plus complexe

Les sélecteurs peuvent également être réellement puissants comme le montre l'exemple suivant. Ici, le premier élément <input name="identifiant"/> dans un <div class="panneau-utilisateur principal"> dans le document est retourné :

var el = document.querySelector("div.panneau-utilisateur.principal input[name='identifiant']");

Spécifications

Spécification Statut Commentaire
Selectors API Level 2
La définition de 'document.querySelector()' dans cette spécification.
Obsolete  
Selectors API Level 1
La définition de 'document.querySelector()' dans cette spécification.
Obsolete Définition initiale

Compatibilité des navigateurs

Nous convertissons les données de compatibilité dans un format JSON. Ce tableau de compatibilité utilise encore l'ancien format car nous n'avons pas encore converti les données qu'il contient. Vous pouvez nous aider en contribuant !

Fonctionnalité Chrome Edge Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Support de base 1 (Oui) 3.5 8 10 3.2
Fonctionnalité Android Edge Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
machin 2.1 (Oui) (Oui) 9 10.0 3.2

Voir aussi

Étiquettes et contributeurs liés au document

Dernière mise à jour par : loella16,