mozilla

Document.createEvent()

Many methods used with createEvent, such as initCustomEvent, are deprecated. Use event constructors instead.

 

Creates an event of the type specified. The returned object should be first initialized and can then be passed to element.dispatchEvent.

Syntax

var event = document.createEvent(type);
  • event is the created Event object.
  • type is a string that represents the type of event to be created. Possible event types include "UIEvents", "MouseEvents", "MutationEvents", and "HTMLEvents". See Notes section for details.

Example

This article demonstrates how to create and dispatch events.

Creating custom events

Events can be created with the Event constructor as follows:

var event = new Event('build');

// Listen for the event.
elem.addEventListener('build', function (e) { ... }, false);

// Dispatch the event.
elem.dispatchEvent(event);

This constructor is supported in most modern browsers (with Internet Explorer being the exception). For a more verbose approach, see the old-fashioned way below.

Adding custom data – CustomEvent()

To add more data to the event object, the CustomEvent interface exists and the detail property can be used to pass custom data.
For example, the event could be created as follows:

var event = new CustomEvent('build', { 'detail': elem.dataset.time });

This will then allow you to access the additional data in the event listener:

function eventHandler(e) {
  log('The time is: ' + e.detail);
}

The old-fashioned way

The older approach to creating events uses APIs inspired by Java. The following shows an example:

// Create the event.
var event = document.createEvent('Event');

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

// Listen for the event.
document.addEventListener('build', function (e) {
  // e.target matches document from above
}, false);

// target can be any Element or other EventTarget.
document.dispatchEvent(event);

Triggering built-in events

This example demonstrates simulating a click (that is programmatically generating a click event) on a checkbox using DOM methods. View the example in action.

function simulateClick() {
  var event = new MouseEvent('click', {
    'view': window,
    'bubbles': true,
    'cancelable': true
  });
  var cb = document.getElementById('checkbox'); 
  var canceled = !cb.dispatchEvent(event);
  if (canceled) {
    // A handler called preventDefault.
    alert("canceled");
  } else {
    // None of the handlers called preventDefault.
    alert("not canceled");
  }
}

Browser compatibility

 

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Event() constructor 15 11 Not supported 11.60 6
Feature Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Basic support ? ? ? ? 6

See also

Notes

Event type strings suitable for passing to createEvent are defined in event modules. Some event modules are defined in DOM Events specifications, some modules are defined in other specification (such as SVG), and some event types are Gecko-specific. See the table below for details.

To-do: add event names to the table too.

Event Module Event type to pass to createEvent Method to be used to initialize the event
DOM Level 2 Events
User Interface event module "UIEvents" event.initUIEvent
Mouse event module "MouseEvents" event.initMouseEvent
Mutation event module "MutationEvents" event.initMutationEvent
HTML event module "HTMLEvents" event.initEvent
DOM Level 3 Events
User Interface event module "UIEvent", "UIEvents" event.initUIEvent
Mouse event module "MouseEvent", "MouseEvents" event.initMouseEvent
Mutation event module "MutationEvent", "MutationEvents" event.initMutationEvent
Mutation name event module (not implemented in Gecko as of June 2006) "MutationNameEvent" event.initMutationNameEvent
Text event module "TextEvent" (Gecko also supports "TextEvents") event.initTextEvent (not implemented)
Keyboard event module "KeyboardEvent" (Gecko also supports "KeyEvents") event.initKeyEvent (Gecko-specific; the DOM 3 Events working draft uses initKeyboardEvent instead)
Custom event module "CustomEvent" event.initCustomEvent
Basic events module "Event" (Gecko also supports "Events") event.initEvent
SVG 1.1 Scripting
SVG "SVGEvents" (Gecko also supports "SVGEvent") event.initEvent
"SVGZoomEvents" (Gecko also supports "SVGZoomEvent") event.initUIEvent
Other event types supported by Gecko
- "MessageEvent" event.initMessageEvent
"MouseScrollEvents", "PopupEvents" event.initMouseEvent
"PopupBlockedEvents" event.initPopupBlockedEvent
"XULCommandEvent", "XULCommandEvents" event.initCommandEvent
Progress Events "ProgressEvent" ProgressEvent.initProgressEvent()Deprecated since Gecko 22.0
Animation Events "AnimationEvent" (or "WebKitAnimationEvent" for WebKit/Blink-based browsers) AnimationEvent.initAnimationEvent()Deprecated since Gecko 23.0
Transition Events "TransitionEvent" (or "WebKitTransitionEvent" for WebKit/Blink-based browsers) TransitionEvent.initTransitionEvent()Deprecated since Gecko 23.0

The reason some events can be created using any of two event type strings is that DOM Level 3 Events changed the event type strings to be singular, while still supporting older plural names for backwards-compatibility.

Specification

Document Tags and Contributors

Last updated by: teoli,
Hide Sidebar