Évènements DOM

Les évènements DOM sont déclenchés pour notifier au code des « changements intéressants » qui peuvent affecter l'exécution du code. Ces changements peuvent résulter d'interactions avec l'utilisateur·ice, comme l'utilisation de la souris ou le redimensionnement d'une fenêtre, de changements dans l'état de l'environnement sous-jacent (par exemple, une batterie faible ou des évènements médiatiques provenant du système d'exploitation), et d'autres causes.

Chaque évènement est représenté par un objet implémentant l'interface Event, et peut avoir d'autres propriétés et/ou champs, permettant d'obtenir des informations supplémentaires au sujet de ce qui s'est produit. La documentation de chaque évènement comporte un tableau (en haut de la page) qui comprend un lien vers l'interface de l'évènement associé et d'autres informations pertinentes. Une liste complète des différents types d'évènements est donnée dans Event > Interfaces basées sur Event.

Cette rubrique fournit un index des principales sortes d'évènements qui peuvent vous intéresser (animation, presse-papiers, workers, etc.) ainsi que les principales classes qui implémentent ces sortes d'évènements. À la fin se trouve une liste exhaustive de tous les évènements documentés.

Index des évènements

Type d'évènement	Description	Documentation
Animation	Les évènements liés à l'API Web Animation API. Utilisé pour répondre aux changements d'état de l'animation (par exemple, lorsqu'une animation commence ou se termine).	Évènements d'animation déclenchés sur `Document`, `Window`, `HTMLElement`.
Récupération asynchrone des données	Évènements liés à l'extraction des données.	Évènements déclenchés sur `AbortSignal`, `XMLHttpRequest`, `FileReader`.
Presse-papiers	Les évènements liés à l'API Clipboard API. Utilisé pour notifier lorsque le contenu est coupé, copié ou collé.	Évènements déclenchés sur `Document`, `Element`, `Window`.
Composition	Évènements liés à la composition ; saisie « indirecte » du texte (au lieu d'utiliser les touches normales du clavier). Par exemple, un texte saisi par un moteur de conversion de la parole en texte, ou l'utilisation de combinaisons de touches spéciales qui modifient les pressions sur le clavier pour représenter de nouveaux caractères dans une autre langue.	Évènements déclenchés sur `Element`.
Transition CSS	Évènements liés aux Transitions CSS. Fournit des évènements de notification lorsque les transitions CSS commencent, s'arrêtent, sont annulées, etc.	Évènements déclenchés sur `Document`, `HTMLElement`, `Window`.
Base de données	Évènements liés aux opérations de la base de données : ouverture, fermeture, transactions, erreurs, etc.	Évènements déclenchés sur `IDBDatabase`, `IDBOpenDBRequest`, `IDBRequest`, `IDBTransaction`.
Mutation du DOM	Évènements liés aux modifications de la hiérarchie et des nœuds du Document Object Model (DOM).	Avertissement : Mutation Events sont dépréciés. L'API Mutation Observers doit être utilisé à la place.
Glisser/Déposer, Roue	Les évènements liés à l'utilisation de l'API Glisser/Déposer et WheelEvent. Les évènements Glisser/Déposer et Roue sont dérivés des évènements de la souris. Bien qu'ils soient déclenchés lors de l'utilisation de la molette de la souris ou du glisser/déposer, ils peuvent également être utilisés avec d'autres matériels appropriés.	Les évènements de Glisser/Déposer déclenchés sur `Document` Les évènements de la Roue déclenchés sur `Document` et `Element`
Ciblage	Les évènements liés aux éléments qui gagnent et perdent la sélection.	Évènements déclenchés sur `Element`, `Window`.
Formulaire	Évènements liés à la construction, la réinitialisation et la soumission de formulaires.	Évènements déclenchés sur `HTMLFormElement`.
Plein écran	Évènements relatifs à l'API Fullscreen API. Utilisé pour notifier la transition entre le mode plein écran et le mode fenêtré, ainsi que les erreurs survenant pendant cette transition.	Évènements déclenchés sur `Document`, `Element`.
Manette de jeu	Évènements relatifs à l'API Gamepad API.	Évènements déclenchés sur `Window`.
Gestes	Les évènements tactiles sont recommandés pour la mise en œuvre des gestes.	Évènements déclenchés sur `Document`, `Element`. En outre, il existe un certain nombre d'évènements de geste non standard : Évènements spécifiques à WebKit non standard sur `Element` : les évènements `gesturestart`, `gesturechange`, `gestureend`.
Historique	Les évènements liés à l'API de Manipulation de l'historique du navigateur.	Évènements déclenchés sur `Window`.
Gestion de l'affichage du contenu des éléments HTML	Évènements liés à la modification de l'état d'un élément d'affichage ou textuel.	Évènements déclenchés sur `HTMLDetailsElement`, `HTMLDialogElement`, `HTMLSlotElement`.
Entrées	Évènements liés aux éléments d'entrée HTML, par ex. `<input>`, `<select>`, ou `<textarea>`.	Évènements déclenchés sur `HTMLElement`, `HTMLInputElement`.
Clavier	Évènements liés à l'utilisation d'un clavier. Utilisé pour notifier lorsque les touches sont déplacées vers le haut, vers le bas, ou simplement pressées.	Évènements déclenchés sur `Document`, `Element`.
Manifeste	Évènements liés à l'installation de Manifeste des applications web.	Évènements déclenchés sur `Window`.
Médias	Évènements liés à l'utilisation des médias (y compris l'API de capture et de diffusion de médias, Web Audio API, Picture-in-Picture API, etc.).	Évènements déclenchés sur `ScriptProcessorNode`, `HTMLMediaElement`, `AudioTrackList`, `AudioScheduledSourceNode`, `MediaRecorder`, `MediaStream`, `MediaStreamTrack`, `VideoTrackList`, `HTMLTrackElement`, `OfflineAudioContext`, `TextTrack`, `TextTrackList`, Element/audio, Element/video.
Messagerie	Évènements liés à la réception par une fenêtre d'un message provenant d'un autre contexte de navigation.	Évènements déclenchés sur `Window`.
Souris	Évènements liés à l'utilisation d'une souris d'ordinateur. Utilisé pour notifier le clic de la souris, le double-clic, les évènements haut et bas, le clic droit, le déplacement dans et hors d'un élément, la sélection de texte, etc. Les évènements de type pointeur constituent une alternative aux évènements de type souris, indépendamment du matériel utilisé. Les évènements de type "glisser" et "roue" sont dérivés des évènements de type "souris".	Les évènements de souris déclenchés sur `Element`
Réseau/Connexion	Évènements liés à l'obtention et à la perte d'une connexion réseau.	Évènements déclenchés sur `Window`. Évènements déclenchés sur `NetworkInformation` (Network Information API).
Paiements	Les évènements liés à l'API Payment Request API.	Évènements déclenchés sur `PaymentRequest`, `PaymentResponse`.
Performance	Évènements liés aux APIs Performance API.	Évènements déclenchés sur `Performance`.
Pointeur	Les évènements liés à l'API Pointer Events API. Fournit une notification agnostique du matériel à partir des dispositifs de pointage, y compris la souris, la souris tactile, le stylo/stylet.	Évènements déclenchés sur `Document`, `HTMLElement`.
Impression	Évènements liés à l'impression.	Évènements déclenchés sur `Window`.
Rejet de promesse	Évènements envoyés au contexte global du script lorsqu'une promesse JavaScript est rejetée.	Évènements déclenchés sur `Window`.
Sockets	Les évènements liés à l'API WebSockets API.	Évènements déclenchés sur `Websocket`.
SVG	Évènements liés aux images SVG.	Évènements déclenchés sur `SVGElement`, `SVGAnimationElement`, `SVGGraphicsElement`.
Sélection de texte	Évènements liés à la sélection du texte.	Évènements déclenchés sur `Document`.
Tactile	Les évènements liés à l'API Évènements tactiles. Fournit des évènements de notification provenant de l'interaction avec un écran tactile (c'est-à-dire l'utilisation d'un doigt ou d'un stylet). Non lié à l'API Force Touch API.	Évènements déclenchés sur `Document`, `Element`.
Réalité virtuelle	Les évènements liés à l'API WebXR Device API. Note : L'API WebVR API (et les évènements associés à `Window`) sont dépréciés.	Évènements déclenchés sur `XRSystem`, `XRSession`, `XRReferenceSpace`.
RTC (communication en temps réel)	Les évènements liés à l'API WebRTC API.	Évènements déclenchés sur `RTCDataChannel`, `RTCDTMFSender`, `RTCIceTransport`, `RTCPeerConnection`.
Évènements envoyés par le serveur	Les évènements liés à l'API des évènements envoyés par le serveur.	Évènements déclenchés sur `EventSource`.
Synthèse vocale	Les évènements liés à l'API Web Speech API.	Évènements déclenchés sur `SpeechSynthesisUtterance`.
Workers	Les évènements liés aux APIs Web Workers API, Service Worker API, Broadcast Channel API, et Channel Messaging API. Utilisé pour répondre aux nouveaux messages et aux erreurs d'envoi de messages. Les travailleurs de service peuvent également être notifiés d'autres évènements, notamment les notifications push, les utilisateur·ice·s qui cliquent sur les notifications affichées, le fait que l'abonnement push a été invalidé, la suppression d'éléments de l'index de contenu, etc.	Évènements déclenchés sur `ServiceWorkerGlobalScope`, `DedicatedWorkerGlobalScope`, `SharedWorkerGlobalScope`, `WorkerGlobalScope`, `Worker`, `WorkerGlobalScope`, `BroadcastChannel`, `MessagePort`.

Créer et déclencher des évènements

En plus des évènements déclenchés par les interfaces intégrées, vous pouvez créer et déclencher vous-même des évènements DOM. Ces évènements sont couramment appelés évènements synthétiques, par opposition aux évènements déclenchés par le navigateur.

Créer des évènements personnalisés

Les évènements peuvent être créés avec le constructeur Event comme suit :

const event = new Event("build");

// Écouter l'évènement.
elem.addEventListener("build", (e) => {
  /* … */
});

// Déclencher l'évènement.
elem.dispatchEvent(event);

Cet exemple utilise la méthode EventTarget.dispatchEvent().

Ajouter des données personnalisées - CustomEvent()

Pour ajouter des données à l'objet évènement, l'interface CustomEvent existe et la propriété detail permet de transmettre des données personnalisées. Par exemple, l'évènement peut être créé ainsi :

const event = new CustomEvent("build", { detail: elem.dataset.time });

Vous pouvez alors accéder à ces données supplémentaires dans l'écouteur d'évènement :

function eventHandler(e) {
  console.log(`L'heure est&nbsp;: ${e.detail}`);
}

Ajouter des données personnalisées - sous-classer Event

L'interface Event peut aussi être sous-classée. Cela est utile pour la réutilisation, pour des données personnalisées plus complexes, ou même pour ajouter des méthodes à l'évènement.

class BuildEvent extends Event {
  #buildTime;

  constructor(buildTime) {
    super("build");
    this.#buildTime = buildTime;
  }

  get buildTime() {
    return this.#buildTime;
  }
}

Ce code définit une classe BuildEvent avec une propriété en lecture seule et un type d'évènement fixe.

L'évènement peut alors être créé ainsi :

const event = new BuildEvent(elem.dataset.time);

Les données supplémentaires sont accessibles dans les écouteurs avec les propriétés personnalisées :

function eventHandler(e) {
  console.log(`L'heure est&nbsp;: ${e.buildTime}`);
}

Propagation des évènements (bubbling)

Il est souvent utile de déclencher un évènement depuis un élément enfant et de le capter sur un ancêtre ; vous pouvez aussi transmettre des données avec l'évènement :

html

<form>
  <textarea></textarea>
</form>

const form = document.querySelector("form");
const textarea = document.querySelector("textarea");

// Créer un nouvel évènement, autoriser la propagation, et transmettre des données avec la propriété "detail"
const eventAwesome = new CustomEvent("awesome", {
  bubbles: true,
  detail: { text: () => textarea.value },
});

// Le formulaire écoute l'évènement personnalisé "awesome" et affiche la valeur transmise
form.addEventListener("awesome", (e) => console.log(e.detail.text()));

// À chaque saisie, la textarea déclenche l'évènement à partir d'elle-même
textarea.addEventListener("input", (e) => e.target.dispatchEvent(eventAwesome));

Créer et déclencher dynamiquement des évènements

Les éléments peuvent écouter des évènements qui n'ont pas encore été créés :

html

<form>
  <textarea></textarea>
</form>

const form = document.querySelector("form");
const textarea = document.querySelector("textarea");

form.addEventListener("awesome", (e) => console.log(e.detail.text()));

textarea.addEventListener("input", function () {
  // Créer et déclencher un évènement à la volée
  // Remarque&nbsp;: on utilise ici une fonction classique pour que "this" représente l'élément
  this.dispatchEvent(
    new CustomEvent("awesome", {
      bubbles: true,
      detail: { text: () => textarea.value },
    }),
  );
});

Déclencher des évènements natifs

Cet exemple montre comment simuler un clic (c'est-à-dire générer un évènement click par programmation) sur une case à cocher à l'aide des méthodes DOM. Voir l'exemple en action ^(angl.).

function simulateClick() {
  const event = new MouseEvent("click", {
    view: window,
    bubbles: true,
    cancelable: true,
  });
  const cb = document.getElementById("checkbox");
  const cancelled = !cb.dispatchEvent(event);

  if (cancelled) {
    // Un gestionnaire a appelé preventDefault.
    alert("annulé");
  } else {
    // Aucun gestionnaire n'a appelé preventDefault.
    alert("non annulé");
  }
}

Enregistrer des gestionnaires d'évènements

Il existe deux méthodes recommandées pour enregistrer des gestionnaires. Le code du gestionnaire peut être exécuté lorsqu'un évènement est déclenché soit en l'assignant à la propriété onevent correspondante de l'élément cible, soit en enregistrant le gestionnaire comme écouteur à l'aide de la méthode addEventListener(). Dans les deux cas, le gestionnaire reçoit un objet conforme à l'interface Event (ou à une interface dérivée). La principale différence est que plusieurs gestionnaires peuvent être ajoutés (ou supprimés) avec les méthodes d'écouteur d'évènements.

Attention : Une troisième méthode, qui consiste à utiliser les attributs HTML onevent, n'est pas recommandée ! Ils alourdissent le balisage, le rendent moins lisible et plus difficile à déboguer. Pour plus d'informations, voir Gestionnaires d'évènements en ligne.

Utiliser les propriétés onevent

Par convention, les objets JavaScript qui déclenchent des évènements possèdent des propriétés "onevent" (nommées en préfixant "on" au nom de l'évènement). Ces propriétés sont appelées pour exécuter le code du gestionnaire associé lorsque l'évènement est déclenché, et peuvent aussi être appelées directement par votre code.

Pour définir le code du gestionnaire, il suffit de l'assigner à la propriété onevent appropriée. Un seul gestionnaire peut être assigné pour chaque évènement sur un élément. Si besoin, le gestionnaire peut être remplacé en assignant une autre fonction à la même propriété.

L'exemple suivant montre comment définir une fonction greet() pour l'évènement click en utilisant la propriété onclick.

const btn = document.querySelector("button");

function greet(event) {
  console.log("greet:", event);
}

btn.onclick = greet;

Notez qu'un objet représentant l'évènement est passé comme premier argument au gestionnaire. Cet objet implémente ou dérive de l'interface Event.

EventTarget.addEventListener

La façon la plus flexible de définir un gestionnaire d'évènement sur un élément est d'utiliser la méthode EventTarget.addEventListener. Cette approche permet d'assigner plusieurs écouteurs à un élément et de les supprimer si besoin, à l'aide de EventTarget.removeEventListener.

Note : La possibilité d'ajouter et de supprimer des gestionnaires permet, par exemple, d'utiliser le même bouton pour différentes actions selon le contexte. De plus, dans des programmes plus complexes, nettoyer les anciens gestionnaires inutilisés peut améliorer l'efficacité.

L'exemple suivant montre comment une fonction greet() peut être définie comme écouteur/gestionnaire pour l'évènement click (vous pouvez utiliser une fonction anonyme si vous le souhaitez). Notez à nouveau que l'évènement est passé comme premier argument au gestionnaire.

const btn = document.querySelector("button");

function greet(event) {
  console.log("greet:", event);
}

btn.addEventListener("click", greet);

La méthode peut aussi prendre des arguments/options supplémentaires pour contrôler la capture ou la suppression des évènements. Plus d'informations sont disponibles sur la page de référence de EventTarget.addEventListener.

Utiliser AbortSignal

Une fonctionnalité notable des écouteurs d'évènements est la possibilité d'utiliser un signal d'abandon pour supprimer plusieurs gestionnaires en même temps.

Cela se fait en passant le même objet AbortSignal à l'appel de addEventListener() pour tous les gestionnaires que vous souhaitez pouvoir supprimer ensemble. Vous pouvez ensuite appeler abort() sur le contrôleur propriétaire du signal, ce qui supprime tous les gestionnaires ajoutés avec ce signal. Par exemple, pour ajouter un gestionnaire que l'on peut supprimer avec un AbortSignal :

const controller = new AbortController();

btn.addEventListener(
  "click",
  (event) => {
    console.log("greet:", event);
  },
  { signal: controller.signal },
); // on passe un AbortSignal à ce gestionnaire

Ce gestionnaire peut ensuite être supprimé ainsi :

controller.abort(); // supprime tous les gestionnaires associés à ce contrôleur

Interaction de plusieurs gestionnaires d'évènements

La propriété IDL onevent (par exemple, element.onclick = ...) et l'attribut HTML onevent (par exemple, <button onclick="...">) ciblent tous deux le même emplacement de gestionnaire unique. Le HTML est chargé avant que JavaScript puisse accéder au même élément, donc en général JavaScript remplace ce qui est défini dans le HTML. Les gestionnaires ajoutés avec addEventListener() sont indépendants. Utiliser onevent ne supprime ni ne remplace les écouteurs ajoutés avec addEventListener(), et inversement.

Lorsqu'un évènement est déclenché, les écouteurs sont appelés en plusieurs phases. Il y a deux phases : capture et bulle (bubbling). En phase de capture, l'évènement part de l'ancêtre le plus haut et descend l'arbre DOM jusqu'à la cible. En phase de bulle, l'évènement remonte en sens inverse. Par défaut, les écouteurs écoutent en phase de bulle, mais ils peuvent écouter en phase de capture en passant capture: true à addEventListener(). Dans une même phase, les écouteurs sont appelés dans l'ordre où ils ont été enregistrés. Le gestionnaire onevent est enregistré la première fois qu'il devient non nul ; les réaffectations ultérieures ne changent que sa fonction de rappel, pas sa position dans l'ordre.

Appeler Event.stopPropagation() empêche l'appel des écouteurs sur d'autres éléments plus loin dans la chaîne de propagation. Event.stopImmediatePropagation() empêche aussi l'appel des autres écouteurs sur le même élément.

Spécifications

Spécification
DOM # events
HTML # events-2

Voir aussi

Aider à améliorer MDN

Apprendre à contribuer

Cette page a été modifiée le 13 mai 2026 par les contributeur·ice·s du MDN.

Voir cette page sur GitHub • Signaler un problème avec ce contenu