JavaScript Custom Events

Written by Swapnil RajaPublished 24 Aug 2026

A custom event lets one part of your code announce something to another.

You are not limited to the events the browser provides.

CustomEvent creates your own, with any data attached.

Example

javascript

document.body.innerHTML = '<div id="cart"></div>';

const cart = document.getElementById("cart");

cart.addEventListener("itemAdded", function (event) {
  console.log("added " + event.detail.name);
});

cart.dispatchEvent(new CustomEvent("itemAdded", {
  detail: { name: "Book" }
}));

PreviousJavaScript Page Load Events NextJavaScript Asynchronous

Example

javascript

document.body.innerHTML = '<div id="box"></div>';

const box = document.getElementById("box");

box.addEventListener("saved", function (event) {
  console.log(event.detail.id + " at " + event.detail.time);
});

box.dispatchEvent(new CustomEvent("saved", {
  detail: { id: 7, time: "now" }
}));

Example

javascript

document.body.innerHTML = '<div id="outer"><div id="inner"></div></div>';

let heard = 0;

document.getElementById("outer").addEventListener("ping", function () {
  heard = heard + 1;
});

document.getElementById("inner").dispatchEvent(new CustomEvent("ping"));
document.getElementById("inner").dispatchEvent(
  new CustomEvent("ping", { bubbles: true })
);

console.log(heard);

Example

javascript

document.addEventListener("themeChanged", function (event) {
  console.log("theme is now " + event.detail);
});

document.dispatchEvent(new CustomEvent("themeChanged", { detail: "dark" }));

Example

javascript

document.body.innerHTML = '<div id="cart"></div>';

const cart = document.getElementById("cart");
const log = [];

cart.addEventListener("itemAdded", function () { log.push("update the badge"); });
cart.addEventListener("itemAdded", function () { log.push("show a message"); });

cart.dispatchEvent(new CustomEvent("itemAdded", { detail: { name: "Book" } }));

console.log(log.join(" / "));

Example

javascript

document.body.innerHTML = '<div id="box"></div>';

const box = document.getElementById("box");

box.addEventListener("refresh", function () {
  console.log("refreshing");
});

box.dispatchEvent(new Event("refresh"));

Complete Example

html

<!DOCTYPE html>
<html>
<head>
  <title>JavaScript Custom Events</title>
</head>
<body>

  <h1>Custom Events</h1>

  <button id="add">Add to cart</button>

  <p id="badge">Items: 0</p>
  <p id="message"></p>

  <script>
    const cart = document.getElementById("add");
    let count = 0;

    cart.addEventListener("click", function () {
      count = count + 1;
      cart.dispatchEvent(new CustomEvent("itemAdded", {
        detail: { name: "Book", total: count }
      }));
    });

    cart.addEventListener("itemAdded", function (event) {
      document.getElementById("badge").textContent = "Items: " + event.detail.total;
    });

    cart.addEventListener("itemAdded", function (event) {
      document.getElementById("message").textContent = "Added " + event.detail.name;
    });
  </script>

</body>
</html>

JavaScript Custom Events

Example

Creating and Firing

Syntax

Passing Data

Example

Custom Events Do Not Bubble by Default

Example

Firing on document

Example

Why Bother?

Example

A Plain Event Works Too

Example

Complete Example

Try It Yourself

Important Points

Conclusion