Custom events

Make one part of your program announce what happened

An event is a message that says "something just happened". A listener is a function that waits for one kind of event and runs when it arrives. You already know built-in events, such as click and submit, from the earlier Events lessons. The browser sends those for you.

A custom event is an event you invent for your own app. You choose its name, such as cart:add, timer:done, or profile:saved. Your own code sends it.

Why is that useful? Say a product button adds tea to the cart. Three parts of the page care:

• the cart badge, which shows how many items are in the cart,
• the analytics logger, which counts what people buy,
• the discount banner, which may show a deal.

The button could call all three parts itself. But then the button must know about every one of them. Instead, the button can announce, "an item was added". Each part that cares listens for that announcement and reacts. The button doesn't need to know who is listening.

You make a custom event with new CustomEvent(type, options). It takes two things:

• type: the event's name, as a string, such as "cart:add".
• options: an object with settings. You can leave it out.

The options object can have four settings. Each one has a job:

• detail holds the data you want to send, such as which item was added. If you leave it out, it is null.
• bubbles says whether the event travels up to the elements around the target. It is false unless you set it.
• cancelable says whether a listener may cancel the event. It is false unless you set it.
• composed is for Web Components; you'll see it near the end of the lesson. It is false unless you set it.

The plain Event class makes events too, with new Event(type, options). But it has no detail. So when listeners need data, use CustomEvent.

1const event = new CustomEvent("cart:add", {2  detail: { id: "tea", name: "Mint tea", qty: 2 },3  bubbles: true,4  cancelable: true,5});6 7console.log(event.type);8console.log(event.detail.name);9console.log(event.bubbles);10console.log(event.cancelable);11console.log(event.isTrusted);

Lines 1 to 5 make the event. Line 1 names it cart:add. Line 2 puts an object with the tea's id, name, and quantity in detail. Lines 3 and 4 turn on bubbles and cancelable.

Lines 7 to 11 print five things:

• Line 7 prints the name, cart:add.
• Line 8 reads inside detail and prints Mint tea.
• Lines 9 and 10 print true and true, because lines 3 and 4 turned those settings on.
• Line 11 prints false. isTrusted is true only for events that come from a real person, like a real click. Your code made this event, so it is false.

Now leave the settings out. This example sets only detail. Then it prints the count and three settings.

1const event = new CustomEvent("cart:updated", {2  detail: { count: 3 },3});4 5console.log(event.detail.count);6console.log(event.bubbles);7console.log(event.cancelable);8console.log(event.composed);

Line 5 prints 3, the count from detail. Lines 6, 7, and 8 print false, false, and false. So an event doesn't bubble, can't be cancelled, and doesn't leave a Web Component, unless you ask for it.

Other code listens for your event by its name. So pick a name that says exactly what happened, such as cart:item-added. The colon is just a habit that makes names easy to read; any string works. What matters is that the name is clear, doesn't sound like a browser event, and is written down for your team.

1const event = new CustomEvent("cart:item-added", {2  detail: { name: "tea" },3});4 5console.log(event.type);6console.log(event.detail.name);

Line 1 names what happened in the app: an item was added to the cart. It is not a browser action like click. Line 2 puts the item's name in detail. Lines 5 and 6 print cart:item-added and tea. A listener can tell what happened and which item it was.

Events aren't only for buttons. Here a Cart class announces each change. extends EventTarget on line 1 gives the class the event methods; you'll learn more about that later in this lesson.

1class Cart extends EventTarget {2  items = [];3 4  add(item) {5    this.items.push(item);6    this.dispatchEvent(new CustomEvent("cart:updated", {7      detail: { count: this.items.length, item },8    }));9  }10}11 12const cart = new Cart();13cart.addEventListener("cart:updated", (event) => {14  console.log("items", event.detail.count, "last", event.detail.item);15});16cart.add("tea");

Line 5 adds the item to the list. Lines 6 to 8 send a cart:updated event. Its detail holds the new count and the item. Lines 13 to 15 add a listener. Line 16 adds tea, so the listener prints items 1 last tea.

detail doesn't make a copy. It holds the very value you pass in. If that value is an object, your code and every listener share the same object. So listeners should only read detail, not change it, unless sharing is what you want.

1const cart = { count: 1 };2const event = new CustomEvent("cart:updated", { detail: cart });3 4event.detail.count = 2;5console.log(cart.count);

Line 2 puts the cart object in detail. Line 4 changes count through event.detail. Line 5 prints 2: the original cart changed too, because it is the same object.

Now try it on a real page. The #shop element holds two product buttons and a cart badge. The buttons don't change the badge themselves. Each button sends a cart:add event with detail. A listener on #shop hears it and updates the badge and the log.

How can a listener on #shop hear an event sent from a button? Through bubbling. With bubbles: true, the event first reaches the button. Then it travels up to each element around the button, one by one. So #shop hears it too.

Use the two toggle buttons in the demo to turn bubbles off, or to add a listener on the button that cancels the event. Then click Add and watch the badge.

1const shop = document.querySelector("#shop");2const badge = document.querySelector("#cart-count");3let items = 0;4 5shop.addEventListener("cart:add", (event) => {6  items = items + event.detail.qty;7  badge.textContent = String(items);8  console.log("Added", event.detail.name);9});10 11button.dispatchEvent(new CustomEvent("cart:add", {12  detail: { id: "tea", name: "Mint tea", qty: 1 },13  bubbles: true,14  cancelable: true,15}));

target.dispatchEvent(event) sends the event from target. It runs the matching listeners synchronously. That means right now, one after another, in the order they were added. Only when they have all finished does the line after dispatchEvent run. There is no waiting, no timer, and no promise.

dispatchEvent also returns true or false. It is almost always true. It is false only when both of these are true:

• the event was made with cancelable: true, and
• at least one listener called event.preventDefault(), which means "please don't do this".

That gives listeners a way to say no before something happens. In this example, a todo list asks its listeners before it deletes item 3.

1const todo = new EventTarget();2 3todo.addEventListener("before-delete", (event) => {4  event.preventDefault();5});6 7const ok = todo.dispatchEvent(new CustomEvent("before-delete", {8  detail: { id: 3 },9  cancelable: true,10}));11 12console.log(ok);

On line 4, the listener calls preventDefault(). Line 9 made the event cancelable, so that call counts. Line 7 stores false in ok, and line 12 prints it. The todo list can check ok and skip the delete.

1const event = new CustomEvent("before-save");2 3event.preventDefault();4console.log(event.defaultPrevented);5console.log(new EventTarget().dispatchEvent(event));

Line 1 makes an event without cancelable: true. Line 3 calls preventDefault(), but it is ignored. Line 4 prints false: defaultPrevented tells you whether the event was cancelled, and it wasn't. Line 5 sends the event from a new EventTarget, an object that can send events (more on it below). It prints true.

Now step through a full run. Two listeners write to a log array. Predict where their entries land in the log.

1const target = new EventTarget();2const log = [];3 4target.addEventListener("status", (event) => {5  log.push("listener A: " + event.detail);6});7 8target.addEventListener("status", (event) => {9  log.push("listener B");10});11 12log.push("before dispatch");Run13const ok = target.dispatchEvent(14  new CustomEvent("status", { detail: "ready", cancelable: true }),15);16log.push("after dispatch: " + ok);17 18console.log(log.join(" | "));

Running listeners right away is useful. A button can ask "did any listener cancel this?" and get the answer on the next line. But it has a cost: a slow listener makes the sender wait. Keep listeners short. Move slow work into a timer, a promise, or another tool that runs later.

EventTarget is the built-in class that gives an object three methods:

• addEventListener, to start listening,
• removeEventListener, to stop listening,
• dispatchEvent, to send an event.

Every element on a page already has these methods. But EventTarget isn't only for page elements. Modern browsers and Node 22 let you make one with new EventTarget(), or extend it in your own class. Then a timer, a downloader, a game level, or a small data store can announce what happened. It doesn't need to know anything about the page.

For a small app, you can even use one plain EventTarget as an event bus. An event bus is one shared object that carries announcements between parts of the app. Each part listens only for the event names it needs.

1const bus = new EventTarget();2 3bus.addEventListener("cart:updated", (event) => {4  console.log("badge", event.detail.count);5});6 7bus.dispatchEvent(new CustomEvent("cart:updated", {8  detail: { count: 2 },9}));

Line 1 makes the bus. Lines 3 to 5 add a badge listener for cart:updated. Lines 7 to 9 send that event with a count of 2, so the listener prints badge 2.

The bus keeps no history and has no methods of its own. It only passes the news from the sender to the listener. In a bigger app, a named service or a framework store makes it clearer which code owns what, and which code removes old listeners.

Now try a Timer class that extends EventTarget. Each tick sends a tick event with the count in detail. After the last tick, it sends a done event. Two listeners hear each tick: a display that shows the count, and a logger that writes a row.

1class Timer extends EventTarget {2  constructor(limit = 3) {3    super();4    this.count = 0;5    this.limit = limit;6  }7 8  tick() {9    this.count += 1;10    this.dispatchEvent(new CustomEvent("tick", {11      detail: { count: this.count, limit: this.limit },12    }));13    if (this.count === this.limit) {14      this.dispatchEvent(new Event("done"));15    }16  }17}

Click Remove logger. The logger listener was added with a { signal } option. A signal comes from an AbortController. When the controller aborts, every listener added with its signal is removed. The display listener keeps working. This is often easier than keeping a copy of each listener function just so you can remove it later.

A callback is a function you hand to other code, so that code can call it later. A callback reaches exactly one function. An event reaches every listener that signed up for it.

So how do you choose? If many parts may care, send an event. If one caller needs one answer, use a callback or return a promise. A promise is an object that gives one result later. Both ways are useful. Pick the one where each part needs to know less about the others.

1function downloadWithCallback(onProgress) {2  onProgress(25);3  onProgress(50);4  onProgress(100);5}6 7downloadWithCallback((percent) => {8  console.log("bar", percent);9});

1const download = new EventTarget();2 3download.addEventListener("progress", (event) => {4  console.log("bar", event.detail.percent);5});6 7download.addEventListener("progress", (event) => {8  console.log("analytics", event.detail.percent);9});10 11for (const percent of [25, 50, 100]) {12  download.dispatchEvent(new CustomEvent("progress", {13    detail: { percent },14  }));15}

Both versions report download progress at 25, 50, and 100 percent. In the first, downloadWithCallback calls the one onProgress function it was given. It prints bar 25, bar 50, and bar 100.

In the second, the loop on lines 11 to 15 sends a progress event three times. Two listeners hear each one: the bar listener and the analytics listener. So each percent prints twice: bar 25, then analytics 25, and so on.

The table compares the two. Each row asks one question; read across to compare the answers.

Sort these real situations. For each card, ask: does one caller need a direct answer? Or do many unrelated parts react to the same news?

Where you will use custom events

Custom events help whenever a small feature should announce something without importing the rest of the app.

• Reusable widgets: a date picker sends date-change when the user picks a date.
• Web Components: a Web Component is a custom HTML element you build yourself. It can send a custom event to the page around it. A later lesson covers Web Components.
• Plain modules: a downloader or timer class extends EventTarget.
• Analytics: a feature sends cart:add. The analytics code listens, and the feature's code doesn't change.

A Web Component can keep its inner parts in a hidden area called a shadow DOM. Normally, an event from inside that area stays inside. The composed: true setting lets the event cross out of it. It is a separate setting from bubbles.

1const event = new CustomEvent("profile:save", {2  composed: true,3});4 5console.log(event.composed);6console.log(event.bubbles);

Line 2 turns on composed, so line 5 prints true. Line 6 prints false. The event still doesn't travel up to the elements around it, because bubbles is its own setting.

Common mistakes and surprises

• “Custom events run later.” No. dispatchEvent runs every listener before it returns.
• “Every custom event bubbles.” No. bubbles is false unless you set it.
• “Event and CustomEvent both have detail.” No. Only CustomEvent has it, so use CustomEvent to send data.
• “dispatchEvent gives back what the listeners return.” No. It returns true or false. false means a listener cancelled the event.
• “Events made by code count as real user actions.” No. Events your code makes have isTrusted set to false.
• “A custom event should reuse a name like click or change.” No. Pick your own name, like cart:add, so no one mixes it up with a browser event.

The table lists each setting, its value when you leave it out, and why that matters.

Key takeaways

• CustomEvent can carry data in detail. A plain Event can't.
• dispatchEvent runs every listener right away. It returns false only when the event is cancelable and a listener called preventDefault().
• Give events clear names of your own. Turn on bubbles, cancelable, or composed only when you need them.
• Your own classes can extend EventTarget. It isn't only for page elements.
• An event tells many listeners that something happened. A callback or a promise gets one result for one caller.

Custom events are named announcements that your code sends, so separate listeners can react to what happens in your app.

Up next: Mouse, pointer & touch.