Revision 1073018 of EventTarget.dispatchEvent()

<p>{{APIRef("DOM Events")}}</p>

<p>Dispatches an {{domxref("Event")}} at the specified {{domxref("EventTarget")}}, invoking the affected {{domxref("EventListener")}}s in the appropriate order. The normal event processing rules (including the capturing and optional bubbling phase) apply to events dispatched manually with <code>dispatchEvent()</code>.</p>

<h2 id="Syntax" name="Syntax">Syntax</h2>

<pre class="syntaxbox">
<em>cancelled</em> = !<em>target</em>.dispatchEvent(<em>event</em>)
</pre>

<h3 id="Properties">Properties</h3>

<ul>
 <li><code>event</code> is the {{domxref("Event")}} object to be dispatched.</li>
 <li><code>target</code> is used to initialize the {{domxref("Event", "", "target")}} and determine which event listeners to invoke.</li>
</ul>

<h3 id="Return_Value">Return Value</h3>

<ul>
 <li>The return value is <code>false</code> if at least one of the event handlers which handled this event called {{domxref("Event.preventDefault()")}}. Otherwise it returns <code>true</code>.</li>
</ul>

<p>The <code>dispatchEvent </code>method throws <code>UNSPECIFIED_EVENT_TYPE_ERR</code> if the event's type was not specified by initializing the event before the method was called, or if the event's type is&nbsp;<code>null</code> or an empty string. Exceptions thrown by event handlers are reported as uncaught exceptions; the event handlers run on a nested callstack: they block the caller until they complete, but exceptions do not propagate to the caller.</p>

<h2 id="Notes" name="Notes">Notes</h2>

<p><code>dispatchEvent</code> is the last step of the create-init-dispatch process, which is used for dispatching events into the implementation's event model. The event can be created using <a href="/en-US/docs/DOM/document.createEvent" title="DOM/document.createEvent">document.createEvent</a> method and initialized using <a href="/en-US/docs/DOM/event.initEvent" title="DOM/event.initEvent">initEvent</a> or other, more specific, initialization methods, such as <a href="/en-US/docs/DOM/event.initMouseEvent" title="DOM/event.initMouseEvent">initMouseEvent</a> or <a href="/en-US/docs/DOM/event.initUIEvent" title="DOM/event.initUIEvent">initUIEvent</a>.</p>

<p>See also the <a href="/en-US/docs/DOM/event" title="DOM/event">Event object reference</a>.</p>

<h2 id="Example" name="Example">Example</h2>

<p>See <a href="/en-US/docs/Web/Guide/DOM/Events/Creating_and_triggering_events" title="/en-US/docs/Web/Guide/DOM/Events/Creating_and_triggering_events">Creating and triggering events</a>.</p>

<h2 id="Specification" name="Specification">Specifications</h2>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td>{{SpecName('DOM WHATWG', '#dom-eventtarget-dispatchevent', 'EventTarget.dispatchEvent()')}}</td>
   <td>{{ Spec2('DOM WHATWG') }}</td>
   <td>&nbsp;</td>
  </tr>
  <tr>
   <td>{{SpecName('DOM4', '#dom-eventtarget-dispatchevent', 'EventTarget.dispatchEvent()')}}</td>
   <td>{{ Spec2('DOM4') }}</td>
   <td>&nbsp;</td>
  </tr>
  <tr>
   <td>{{SpecName('DOM2 Events', '#Events-EventTarget-dispatchEvent', 'EventTarget.dispatchEvent()')}}</td>
   <td>{{ Spec2('DOM2 Events') }}</td>
   <td>Initial definition.</td>
  </tr>
 </tbody>
</table>

<h2 id="Browser_Compatibility" name="Browser_Compatibility">Browser compatibility</h2>

<p>{{ CompatibilityTable() }}</p>

<div id="compat-desktop">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Chrome</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari (WebKit)</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>4</td>
   <td>2</td>
   <td>9 [1]</td>
   <td>9.64 (probably earlier)</td>
   <td>3.2 (probably earlier)</td>
  </tr>
 </tbody>
</table>
</div>

<div id="compat-mobile">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Android</th>
   <th>Firefox Mobile (Gecko)</th>
   <th>IE Phone</th>
   <th>Opera Mobile</th>
   <th>Safari Mobile</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
  </tr>
 </tbody>
</table>
</div>

<p>[1]: Earlier versions of IE instead only support the proprietary {{domxref("EventTarget.fireEvent()")}} method.</p>