JavaScript Document createEvent() Method

What You’ll Learn

document.createEvent() is a deprecated instance method that creates an Event object of a named interface type (see MDN Document: createEvent()). Learn the old create → init → dispatch flow, why MDN warns against it, and how modern constructors replace it — with five examples and try-it labs.

Introduction

Before event constructors were widely available, scripts built synthetic events like this: create an empty event with document.createEvent(type), fill it with an init* method, then fire it with dispatchEvent.

That pattern still works in many browsers for compatibility, but MDN labels createEvent deprecated and warns that related init* APIs are deprecated too. Today you write new Event("name", { bubbles: true }) in one step.

Related tutorials: createElement(), createElementNS().

Understanding document.createEvent()

An instance method on the page’s document object (MDN Document interface).

• Parameter — type: string naming the event interface family (MDN).
• Return value — an Event object (MDN).
• Not finished yet — you must initialize (for example initEvent) before dispatch.
• Dispatch — pass the event to EventTarget.dispatchEvent (MDN).
• Modern path — constructors create and configure events in one expression.
• Status — deprecated; prefer constructors (MDN).

📝 Syntax

General form of Document.createEvent (MDN):

createEvent(type)

Parameters

• type — string for the event interface to create. MDN examples include "UIEvents", "MouseEvents", "MutationEvents", and "HTMLEvents". The plain MDN sample uses "Event".

Return value

An Event object (MDN). Initialize it, then dispatch it.

MDN legacy pattern

// Create the event.
const event = document.createEvent("Event");

// Define that the event name is 'build'.
event.initEvent("build", true, true);

// Listen for the event.
elem.addEventListener("build", (e) => {
  // e.target matches elem
});

// Target can be any Element or other EventTarget.
elem.dispatchEvent(event);

Modern replacement

const event = new Event("build", { bubbles: true, cancelable: true });
elem.addEventListener("build", (e) => {
  // e.target matches elem
});
elem.dispatchEvent(event);

📋 Common type strings (legacy)

MDN notes that suitable type strings are listed in the DOM standard, and that most event objects now have constructors instead.

⚖️ createEvent vs modern constructors

Examples Gallery

Examples follow MDN Document: createEvent() and show the modern replacement you should prefer.

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

const event = document.createEvent("Event");
event.initEvent("build", true, true);

elem.addEventListener("build", () => {
  console.log("build fired on", elem.id);
});

elem.dispatchEvent(event);
// "build fired on box"

build fired on box

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

const event = new Event("build", { bubbles: true, cancelable: true });

elem.addEventListener("build", () => {
  console.log("modern build fired");
});

elem.dispatchEvent(event);
// "modern build fired"

modern build fired

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

elem.addEventListener("order", (e) => {
  console.log("qty:", e.detail.qty);
});

const event = new CustomEvent("order", {
  detail: { qty: 3 },
  bubbles: true
});

elem.dispatchEvent(event);
// "qty: 3"

qty: 3

// Legacy (deprecated path — for reading old code only):
const legacy = document.createEvent("MouseEvents");
legacy.initMouseEvent(
  "click", true, true, window,
  0, 0, 0, 0, 0,
  false, false, false, false,
  0, null
);

// Modern:
const modern = new MouseEvent("click", {
  bubbles: true,
  cancelable: true,
  view: window
});

console.log(legacy.type, modern.type); // "click" "click"
console.log(modern instanceof MouseEvent); // true

click click
true

const parent = document.getElementById("parent");
const child = document.getElementById("child");

parent.addEventListener("ping", () => console.log("parent heard ping"));

const event = document.createEvent("Event");
event.initEvent("ping", true, false); // bubbles: true, cancelable: false

child.dispatchEvent(event);
// "parent heard ping"  (because bubbles is true)

console.log(event.bubbles, event.cancelable); // true false

parent heard ping
true false

🚀 Common Use Cases

• Reading legacy tutorials — recognize create → init → dispatch samples.
• Migrating old apps — replace createEvent with constructors.
• Teaching event objects — show that synthetic events still use dispatchEvent.
• Not for new features — do not introduce createEvent in fresh code (MDN).
• Custom component messaging — use CustomEvent + detail.
• Automated UI tests — prefer MouseEvent / KeyboardEvent constructors.

📝 Notes

• MDN: Deprecated — avoid in new code.
• MDN warning: many methods used with createEvent (such as initCustomEvent) are also deprecated.
• Returned objects must be initialized before dispatchEvent (MDN).
• Most event objects now have constructors — the recommended approach (MDN Notes).
• dispatchEvent itself is still the modern way to fire synthetic events.
• Related: createElement(), createElementNS().

💡 Best Practices