Custom Events

What Are Custom Events?

Custom Events allow Web Components to communicate with the outside page, parent components, or application JavaScript by dispatching their own events.

Instead of exposing internal methods or DOM structure, a Web Component can send meaningful events like user-selected, cart-updated, or modal-closed.

Basic Custom Event Example

const event = new CustomEvent("user-selected", {
  detail: {
    id: 101,
    name: "John"
  }
});

element.dispatchEvent(event);

The event name is user-selected, and custom data is passed through the detail object.

Custom Events in Web Components

class AppButton extends HTMLElement {
  constructor() {
    super();

    this.attachShadow({ mode: "open" });

    this.shadowRoot.innerHTML = `
      <button type="button">
        <slot>Click Me</slot>
      </button>
    `;
  }

  connectedCallback() {
    const button = this.shadowRoot.querySelector("button");

    button.addEventListener("click", () => {
      this.dispatchEvent(new CustomEvent("app-click", {
        detail: {
          message: "Button clicked"
        },
        bubbles: true,
        composed: true
      }));
    });
  }
}

customElements.define("app-button", AppButton);

<app-button>Save</app-button>

<script>
  const button = document.querySelector("app-button");

  button.addEventListener("app-click", event => {
    console.log(event.detail.message);
  });
</script>

The component dispatches an app-click event when the internal button is clicked. The outside page listens to the event without accessing the internal Shadow DOM.

How Custom Events Work

Passing Data With detail

this.dispatchEvent(new CustomEvent("product-added", {
  detail: {
    id: "p101",
    name: "Wireless Mouse",
    price: 29.99,
    quantity: 1
  },
  bubbles: true,
  composed: true
}));

document.addEventListener("product-added", event => {
  console.log(event.detail.name);
  console.log(event.detail.quantity);
});

Use detail to pass useful information from the component to the outside application.

bubbles and composed

this.dispatchEvent(new CustomEvent("modal-close", {
  detail: {
    reason: "escape-key"
  },
  bubbles: true,
  composed: true,
  cancelable: true
}));

For most Web Component communication, use bubbles: true and composed: true so parent components can listen to the event.

Cancelable Custom Events

const event = new CustomEvent("before-delete", {
  detail: {
    id: 10
  },
  bubbles: true,
  composed: true,
  cancelable: true
});

const allowed = this.dispatchEvent(event);

if (!allowed) {
  console.log("Delete action was canceled");
  return;
}

this.deleteItem();

document.addEventListener("before-delete", event => {
  const confirmDelete = window.confirm("Delete this item?");

  if (!confirmDelete) {
    event.preventDefault();
  }
});

Cancelable events allow outside code to stop an action before the component continues.

Custom Event Naming Patterns

Listening From a Parent Element

<section id="cart">
  <product-card product-id="101"></product-card>
</section>

<script>
  const cart = document.querySelector("#cart");

  cart.addEventListener("product-added", event => {
    console.log("Product added:", event.detail);
  });
</script>

Because the event bubbles, the parent element can listen for events from child Web Components.

Custom Events and Shadow DOM

this.shadowRoot.querySelector("button").addEventListener("click", () => {
  this.dispatchEvent(new CustomEvent("user-action", {
    detail: {
      action: "save"
    },
    bubbles: true,
    composed: true
  }));
});

When using Shadow DOM, composed: true is important because it allows the event to leave the component and reach external listeners.

Custom Events vs Callback Properties

When to Use Custom Events

• You want a Web Component to notify the outside page about actions.
• You need parent components to listen for child component changes.
• You want to avoid exposing internal Shadow DOM structure.
• You are building reusable design system components.
• You need multiple listeners for the same component event.
• You want framework-independent communication.

Common Custom Event Use Cases

• Button clicked: app-click
• Modal closed: modal-closed
• Tab selected: tab-selected
• Form submitted: form-submitted
• Input value changed: value-changed
• Product added to cart: product-added

Custom Events Best Practices

• Use clear event names like item-selected or value-changed.
• Use kebab-case for custom event names.
• Pass useful data through detail.
• Use bubbles: true for parent-level communication.
• Use composed: true when events must cross Shadow DOM.
• Use cancelable: true only when outside code can stop the action.
• Document event names and detail payload structure.

Common Custom Event Mistakes

• Forgetting to use composed: true inside Shadow DOM.
• Forgetting bubbles: true when parent listeners are needed.
• Using unclear event names like change or click2.
• Putting too much unrelated data inside detail.
• Dispatching events before the component is ready.
• Using callbacks when native DOM events would be cleaner.
• Not documenting custom events for component consumers.

Key Takeaways

• Custom Events help Web Components communicate with the outside page.
• Use new CustomEvent() to create a custom event.
• Use detail to pass custom data.
• Use bubbles: true for parent listeners.
• Use composed: true when working with Shadow DOM.
• Custom Events are a clean public API for reusable components.