Introduction to events

What events are

A web page can react to people. They click buttons, press keys, type text, and move the mouse. Each of these things is an event. An event is the browser's message that something just happened. Your own code can create events too.

A listener is a function you give the browser for one kind of event on one element. When that event happens there, the browser calls your function. It also passes in an event object: an object full of facts about the event. If you know callbacks, a listener is a callback that the browser calls for you.

1const log = [];2button.addEventListener("click", () => log.push("listener"));3log.push("before");4button.dispatchEvent(new Event("click"));5log.push("after");6console.log(log.join(" > "));

Line 1 makes an empty log array. Line 2 adds a listener to button. Line 3 puts "before" in the log.

Line 4 makes a click event with new Event("click") and hands it to the button with dispatchEvent. To dispatch an event means to deliver it and call its listeners. The browser calls the listener right away, before line 5 runs. So line 6 prints "before > listener > after".

1const details = [];2button.addEventListener("click", (event) => {3  details.push(event.type + ":" + event.currentTarget.id);4});5button.dispatchEvent(new Event("click"));6console.log(details[0]);

Line 2 adds a listener. When it runs, it gets the event object as event. Line 3 reads two facts from it:

• event.type is the event's name, "click".
• event.currentTarget.id is the id of the element that owns this listener, "save".

Line 5 sends a click, and line 6 prints "click:save".

In this lesson you will:

• look inside real event objects;
• see why removeEventListener sometimes fails, and fix it;
• try the once, passive, and signal options;
• step through the order in which listeners are added and called.

You call it like this: element.addEventListener(type, listener, options). It takes three things:

• type is the event's name, as a string. For example, "click", "keydown" (a key goes down), or "input" (the text in a field changes).
• listener is the function the browser will call later. It can also be an object with a handleEvent method; you'll see that near the end.
• options is optional. It is usually an object of extra rules. Older code passes true or false here instead. That value is called useCapture.

1const button = document.querySelector("#save");2const status = document.querySelector("#status");3 4button.addEventListener("click", (event) => {5  status.textContent = "Saved at " + Math.round(event.timeStamp) + "ms";6});

Lines 1 and 2 find two elements on the page with document.querySelector. Line 4 adds the listener. It does not run the arrow function yet. It only stores it.

Later, when someone clicks the button, the browser calls the function. Line 5 then writes a message into status. event.timeStamp is the time of the click, in milliseconds since the page started loading. Math.round drops the decimals.

The listener runs to its end before the browser finishes the click. So any change it makes, such as new text, is already done when the click is over.

Each row of the table is one of the three things you pass in.

You can add many listeners to the same element for the same event. Each one runs. There is one exception: if a new listener matches one that is already there, the browser ignores it. A match means all three of these are the same:

• the event type;
• the function (the very same function object, not just the same code);
• the capture value (true or false).

Every listener gets an event object. It tells you:

• what happened: type, such as "click";
• where it started: target;
• when it happened: timeStamp;
• whether a real person caused it: isTrusted;
• extra facts for that kind of event. A key event has key and code. A mouse or pointer event has the pointer's position and which button was pressed. (A pointer is a mouse, a pen, or a finger.)

A key event has two names for the key:

• key is what the key typed, such as "A". Use it for text and for commands.
• code is which physical key was pressed, such as "KeyA". It stays the same on every keyboard layout. Use it when the key's place matters, as in game controls.

currentTarget is only set while the listener runs. Afterwards it is null, so read it inside the listener.

Try the inspector below. Tick the event types you want to watch. Then click, type, or press Tab to move through the controls. Each event adds a line to the log.

The "Dispatch a fake click" button makes its own click with new MouseEvent("click"). Code made that event, not a person, so the log shows trusted=false. Your own clicks show trusted=true.

1const controls = document.querySelector("#inspector");2const log = document.querySelector("#event-log");3 4function inspect(event) {5  const details = {6    type: event.type,7    target: event.target.id,8    currentTarget: event.currentTarget.id,9    timeStamp: Math.round(event.timeStamp),10    isTrusted: event.isTrusted,11    key: event.key,12    code: event.code,13    button: event.button,14    clientX: event.clientX,15    clientY: event.clientY,16  };17  log.prepend(JSON.stringify(details));18}19 20controls.addEventListener("click", inspect);21controls.addEventListener("keydown", inspect);22controls.addEventListener("input", inspect);

Two fields are easy to mix up:

• event.target is the element where the event started.
• event.currentTarget is the element whose listener is running now.

In this lesson, each listener sits on the element it reads, so the two are the same. The next lesson, Bubbling & capturing, shows when they differ.

1button.addEventListener("click", (event) => {2  console.log(event.type + ":" + event.target.id + ":" + Math.round(event.timeStamp));3});4button.dispatchEvent(new Event("click"));

Line 2 joins three facts with colons: the event's name, the id of the element where it started, and its time, rounded. Line 4 sends a click, so the listener prints "click:save:12".

Here the time is a sample value, 12. When you run the code, you will see a different number, because a real time is new for every event. So compare two times instead of expecting one exact value.

removeEventListener(type, listener, options) takes a listener off an element. It only removes a listener that matches exactly:

• the same event type;
• the same function object;
• the same capture value.

The other options, such as once and passive, don't count for the match. Only capture does.

1const button = document.querySelector("#alarm");2let rings = 0;3 4button.addEventListener("click", () => rings++);5button.removeEventListener("click", () => rings++);6button.click(); // rings is 1: the first arrow is still installed7 8function ring() { rings++; }9button.addEventListener("click", ring, { capture: true });10button.removeEventListener("click", ring, { capture: false });11button.click(); // rings is 3: capture did not match12button.removeEventListener("click", ring, { capture: true });

1let saves = 0;2function save() {3  saves++;4}5 6button.addEventListener("click", save);7button.removeEventListener("click", save);8button.dispatchEvent(new Event("click"));9console.log(saves);

Line 2 creates one function, save. The name save is a reference to it: it points at that one exact function object. Line 6 adds it, and line 7 removes that same function.

Line 8 sends a click, but no listener is left to call. So saves stays at 0, and line 9 prints 0.

The third argument, options, can hold three useful rules:

• { once: true } removes the listener after its first call.
• { passive: true } is a promise: this listener will not stop the browser's default action. A default action is what the browser does on its own, such as scrolling the page or ticking a checkbox.
• { signal } links the listener to an AbortController. An AbortController is an object with a signal and an abort() method. Calling abort() removes every listener that got its signal.

The Cancellation with AbortController lesson uses the same signal to stop other kinds of work.

1let notices = 0;2button.addEventListener("click", () => notices++, { once: true });3button.dispatchEvent(new Event("click"));4button.dispatchEvent(new Event("click"));5console.log(notices);

Line 2 adds a listener with { once: true }. Lines 3 and 4 send two clicks. The browser removes the listener right after the first one. So only one click counts, and line 5 prints 1. Use this for a welcome message or a tip you show only once.

1const controller = new AbortController();2 3button.addEventListener("click", celebrate, { once: true });4first.addEventListener("click", log, { signal: controller.signal });5second.addEventListener("pointerdown", log, { signal: controller.signal });6third.addEventListener("keydown", log, { signal: controller.signal });7 8checkbox.addEventListener("click", (event) => {9  event.preventDefault();10  console.log(event.defaultPrevented);11}, { passive: true });12 13controller.abort();

A passive listener can still call preventDefault(). Normally, preventDefault() stops the default action. In a passive listener, the browser ignores it and may print a warning in the console.

Some browsers make certain listeners passive on their own, so that scrolling stays smooth. This happens for wheel, touchstart, and touchmove listeners on window, document, or body. If your listener must stop the default action, say so: pass { passive: false }.

Once a signal is aborted, it stays aborted. Adding a listener with that old signal adds nothing. So make a new AbortController each time you build a new part of the page, and abort the old one when you clean up.

Two moments matter:

• Registration is when addEventListener stores a listener for later.
• Dispatch is when the event happens and the browser calls the listeners.

During dispatch, the listeners on one element run one after another, in the order they were added. Each one finishes before the next one starts. If you add the same function twice, with the same type and capture value, it is stored only once.

1const log = [];Run2const button = document.querySelector("#save");3function first(event) { log.push("first:" + (this === event.currentTarget)); }4const second = (event) => log.push("second:" + (this === event.currentTarget));5 6button.addEventListener("click", first);7button.addEventListener("click", second);8button.addEventListener("click", first); // ignored: same type + function + capture9button.dispatchEvent(new Event("click"));10console.log(log.join(" | "));

Look at this in the replay. In a regular function listener, this is event.currentTarget, the element. An arrow function has no this of its own. It uses the outer this, from the code around it.

So it is safer to read event.currentTarget. It works in both kinds of function. The this keyword lesson explains the full rule.

You will still see onclick in older code. It is a property on the element, and a property holds one value. So it holds one handler. Assigning a new function replaces the old one.

addEventListener can store many listeners side by side. That is why modern code uses it.

You may also see an HTML attribute such as <button onclick="save()">. Avoid it. It mixes JavaScript into the HTML, and it is hard to combine with other code safely.

1const button = document.querySelector("button");2 3button.onclick = () => console.log("first property handler");4button.onclick = () => console.log("second property handler");5 6button.addEventListener("click", () => console.log("listener A"));7button.addEventListener("click", () => console.log("listener B"));8 9const logger = {10  handleEvent(event) {11    console.log("object saw " + event.type);12  },13};14button.addEventListener("click", logger);

1const calls = [];2const logger = {3  handleEvent(event) {4    calls.push(event.type);5  },6};7button.addEventListener("click", logger);8button.dispatchEvent(new Event("click"));9console.log(calls.join(", "));

Line 2 creates an object with a method named handleEvent. That name is special. Line 7 passes the whole object to addEventListener. When line 8 sends the click, the browser calls the object's handleEvent method. So line 9 prints "click".

Keep the object in a variable if you want to remove it later. A new object would not match.

1const calls = [];2const card = {};3card.onclick = () => calls.push("first");4card.onclick = () => calls.push("second");5card.onclick();6console.log(calls.join(", "));

Line 2 makes a plain object, card. Line 3 puts a function in its onclick property. Line 4 puts a second function there, which replaces the first. Line 5 calls the one that is left, so line 6 prints "second".

When several parts of an app need to hear the same click, use addEventListener.

Each row of the table is one way to attach event code. Read across: how many handlers it can hold, and whether to use it.

Where you will use events

Real pages use events everywhere:

• A menu opens on click.
• A search box shows suggestions on input.
• A keyboard shortcut listens for keydown.
• A drag tool listens for pointerdown, pointermove, and pointerup.
• A cleanup function removes listeners when a part of the page goes away.

1function mountSearch(input, results) {2  const controller = new AbortController();3  const { signal } = controller;4 5  input.addEventListener("input", updateResults, { signal });6  input.addEventListener("keydown", closeOnEscape, { signal });7 8  function updateResults(event) {9    results.textContent = "Searching for " + event.currentTarget.value;10  }11 12  function closeOnEscape(event) {13    if (event.key === "Escape") results.textContent = "";14  }15 16  return () => controller.abort();17}

Line 2 creates one AbortController, and line 3 takes its signal. Lines 5 and 6 pass that signal to two listeners. Line 9 shows the search text as the user types. Line 13 clears the results when the user presses Escape.

Line 16 returns a cleanup function. Calling it aborts the controller, which removes both listeners at once.

This pattern also works next to UI libraries such as React. Let the library draw its own elements. Add real DOM listeners in its setup step (in React, an effect), and remove them in its cleanup step. If you create elements by hand, put them inside a container the library does not touch.

Keep the cleanup next to the setup. If you forget it, a hidden or replaced part of the page keeps its listeners. They still use old data, and the next time the part appears, the same work runs twice.

Common misconceptions

• "addEventListener runs my function now." It only stores the function. The browser calls it later, when the event happens.
• "Two arrows with the same code are the same listener." Each arrow is a separate function object, so they don't match.
• "target and currentTarget are always the same." They are the same when the event starts on the element that has the listener. They differ when it starts inside a child element; the next lesson shows how.
• "passive just makes code faster." passive is a promise not to stop the default action. The speed comes from that promise: the browser can scroll right away, without waiting for your listener.
• "dispatchEvent creates a real user event." An event your code makes still calls the listeners, but its isTrusted is false.
• "onclick is the same as addEventListener." The onclick property holds one function. addEventListener can hold many.

Each row of the table is one word from this lesson. Read across: what it means, then an everyday comparison.

Key takeaways

• addEventListener(type, listener, options) stores a function for an event that happens later.
• The event object tells you the event's type, where it started (target), whose listener is running (currentTarget), when it happened, whether a person caused it, and extra facts for that kind of event.
• removeEventListener needs the same function object and the same capture value.
• once removes a listener after one call. passive promises not to stop the default action. signal removes a listener when its controller aborts.
• The onclick property holds one function. addEventListener can hold many.

An event listener is a function the browser calls when a named event happens on an element.

Up next: Bubbling & capturing.