Document Object Model (DOM) Level 3 Events Specification

W3C

Document Object Model (DOM) Level 3 Events Specification

W3C Working Draft 25 September 2014

This version:
http://www.w3.org/TR/2014/WD-DOM-Level-3-Events-20140925/
Latest published version:
http://www.w3.org/TR/DOM-Level-3-Events/
Latest editor's draft:
https://dvcs.w3.org/hg/dom3events/raw-file/tip/html/DOM3-Events.html
Previous version:
http://www.w3.org/TR/2013/WD-DOM-Level-3-Events-20131105/
Editors:
Gary Kacmarcik, Google, Inc. (Jun 2013 - present)
Travis Leithead, Microsoft Corp. (Feb 2012 - present)
Jacob Rossi, Microsoft Corp. (Mar 2011 - Oct 2011)
Doug Schepers, W3C (Mar 2008 - May 2011)
Björn Höhrmann, Invited Expert (until Jan 2008)
Philippe Le Hégaret, W3C (until Nov 2003)
Tom Pixley, Netscape Communications Corporation (until Jul 2002)

Copyright © 2014 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C liability, trademark and document use rules apply.

Abstract

This specification defines the Document Object Model Events Level 3, a generic platform- and language-neutral event system which allows registration of event handlers, describes event flow through a tree structure, and provides basic contextual information for each event. The Document Object Model Events Level 3 builds on the Document Object Model Events Level 2 [DOM2 Events].

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document is a Working Draft of the Document Object Model Level 3 Events (DOM3 Events) specification. It is expected that this specification will progress to W3C Recommendation status after review and refinement.

This document is produced by the Web Applications WG, part of the Rich Web Clients Activity in the W3C Interaction Domain. It is expected that this document will progress along the W3C's Recommendation track. Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and MAY be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

You can find the latest Editor's Draft of this document in the W3C's Mercurial repository, which is updated on a regular basis.

Implementers should be aware that this document is not stable. Implementers who are not taking part in the discussions are likely to find the specification changing out from under them in incompatible ways. Vendors interested in implementing this document before it eventually reaches the Candidate Recommendation stage should join the aforementioned mailing lists and take part in the discussions.

This document was published by the Web Applications Working Group as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to www-dom@w3.org (subscribe, archives). All comments are welcome.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 August 2014 W3C Process Document.

Table of Contents

1. Introduction

1.1 Overview

DOM Events is designed with two main goals. The first goal is the design of an event system which allows registration of event listeners and describes event flow through a tree structure. Additionally, the specification will provide standard modules of events for user interface control and document mutation notifications, including defined contextual information for each of these event modules.

The second goal of DOM Events is to provide a common subset of the current event systems used in existing browsers. This is intended to foster interoperability of existing scripts and content. It is not expected that this goal will be met with full backwards compatibility. However, the specification attempts to achieve this when possible.

1.2 Conformance

This section is normative.

Within this specification, the key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL are to be interpreted as described in [RFC2119].

This specification is to be understood in the context of the DOM Level 3 Core specification [DOM3 Core] and the general considerations for DOM implementations apply. For example, handling of namespace URIs is discussed in XML Namespaces. For additional information about conformance, please see the DOM Level 3 Core specification [DOM3 Core]. A user agent is not required to conform to the entirety of another specification in order to conform to this specification, but it MUST conform to the specific parts of any other specification which are called out in this specification (e.g., a conforming DOM3 Events user agent MUST support the DOMString data type as defined in Web IDL, but need not support every method or data type defined in Web IDL in order to conform to DOM3 Events).

This specification defines several classes of conformance for different user agents, specifications, and content authors:

Web browsers and other dynamic or interactive user agents

A dynamic or interactive user agent, referred to here as a browser (be it a Web browser, AT (Accessibility Technology) application, or other similar program), conforms to DOM Level 3 Events if it supports:

  • the Core module defined in [DOM3 Core]
  • the Event dispatch and DOM event flow mechanism
  • all the interfaces and events with their associated methods, attributes, and semantics defined in this specification with the exception of those marked as deprecated (a conforming user agent MAY implement the deprecated interfaces, events, or APIs for backwards compatibility, but is not required to do so in order to be conforming)
  • the complete set of key and code values defined in [DOM3 key Values] and [DOM3 code Values] (subject to platform availability), and
  • all other normative requirements defined in this specification.

A conforming browser MUST dispatch events appropriate to the given EventTarget when the conditions defined for that event type have been met.

A browser conforms specifically to DOM Level 3 Events if it implements the interfaces and related event types specified in Event Types.

A conforming browser MUST support scripting, declarative interactivity, or some other means of detecting and dispatching events in the manner described by this specification, and MUST support the APIs specified for that event type.

In addition to meeting all other conformance criteria, a conforming browser MAY implement features of this specification marked as deprecated, for backwards compatibility with existing content, but such implementation is discouraged.

A conforming browser MAY also support features not found in this specification, but which use the Event dispatch and DOM event flow mechanism, interfaces, events, or other features defined in DOM Level 3 Events, and MAY implement additional interfaces and event types appropriate to that implementation. Such features can be later standardized in future specifications.

A browser which does not conform to all required portions of this specification MUST NOT claim conformance to DOM Level 3 Events. Such an implementation which does conform to portions of this specification MAY claim conformance to those specific portions.

A conforming browser MUST also be a conforming implementation of the IDL fragments in this specification, as described in the Web IDL specification [WEBIDL].

Authoring tools

A content authoring tool conforms to DOM Level 3 Events if it produces content which uses the event types and Event dispatch and DOM event flow model, consistent in a manner as defined in this specification.

A content authoring tool MUST NOT claim conformance to DOM Level 3 Events for content it produces which uses features of this specification marked as deprecated in this specification.

A conforming content authoring tool SHOULD provide to the content author a means to use all event types and interfaces appropriate to all host languages in the content document being produced.

Content authors and content

A content author creates conforming DOM Level 3 Events content if that content uses the event types and Event dispatch and DOM event flow model, consistent in a manner as defined in this specification.

A content author SHOULD NOT use features of this specification marked as deprecated, but SHOULD rely instead upon replacement mechanisms defined in this specification and elsewhere.

Conforming content MUST use the semantics of the interfaces and event types as described in this specification.

Authoring Note: Content authors are advised to follow best practices as described in accessibility and internationalization guideline specifications.

Specifications and host languages

A specification or host language conforms to DOM Level 3 Events if it references and uses the Event dispatch and DOM event flow mechanism, interfaces, events, or other features defined in [DOM4], and does not extend these features in incompatible ways.

A specification or host language conforms specifically to DOM Level 3 Events if it references and uses the interfaces and related event types specified in Event Types. A conforming specification MAY define additional interfaces and event types appropriate to that specification, or MAY extend the DOM Level 3 Events interfaces and event types in a manner that does not contradict or conflict with the definitions of those interfaces and event types in this specification.

Specifications or host languages which reference DOM Level 3 Events SHOULD NOT use or recommend features of this specification marked as deprecated, but SHOULD use or recommend the indicated replacement for that the feature (if available).

1.3 Stylistic Conventions

This specification follows the Proposed W3C Specification Conventions, with the following supplemental additions:

Key and character values
  • Names of key values are shown as: '=' (e.g., the value of KeyboardEvent.key).
  • Names of key codes are shown as: 'Equal' (e.g., the value of KeyboardEvent.code).
  • Character values of keys are shown as: '\u003d' (e.g., the code point of the key value).
  • Glyphs representing character values are shown as: '=' (e.g., the key cap or font associated with a character value).

In addition, certain terms are used in this specification with particular meanings. The term implementation applies to a browser, content authoring tool, or other user agent that implements this specification, while a content author is a person who writes script or code that takes advantage of the interfaces, methods, attributes, events, and other features described in this specification in order to make Web applications, and a user is the person who uses those Web applications in an implementation.

2. Issues

Issue 1

Open issues in this specification are called out using this convention.

3. DOM Event Architecture

This section is informative.

3.1 Event dispatch and DOM event flow

This section defines the event dispatch mechanism of the event model defined in this specification. Applications MAY dispatch event objects using the EventTarget.dispatchEvent() method, and implementations MUST dispatch event objects as if through this method. The behavior of this method depends on the event flow associated with the underlying object. An event flow describes how event objects propagate through a data structure. As an example, when an event object is dispatched to an element in an XML document, the object propagates through parts of the document, as determined by the DOM event flow which is defined at the end of this section.

Graphical representation of an event dispatched in a DOM tree using the DOM event flow
Fig. 1 Graphical representation of an event dispatched in a DOM tree using the DOM event flow

Event objects are dispatched to an event target. At the beginning of the dispatch, implementations MUST first determine the event object's propagation path.

The propagation path MUST be an ordered list of current event targets through which the event object MUST pass. For DOM implementations, the propagation path MUST reflect the hierarchical tree structure of the document. The last item in the list MUST be the event target. The preceding items in the list are referred to as the target's ancestors, and the immediately preceding item as the target's parent. Once determined, the propagation path MUST NOT be changed. For DOM implementations, this applies even if an element in the propagation path is moved within the DOM or removed from the DOM.

In the DOM event flow, event listeners might change the position of the event target in the document while the event object is being dispatched. Such changes do not affect the propagation path.

Note that event listeners are not copied over when Node are copied using methods such as Node.cloneNode or Range.cloneContents [DOM Range].

Exceptions thrown inside event listeners MUST NOT stop the propagation of the event or affect the propagation path. The exception itself MUST NOT propagate outside the scope of the event handler.

In the following code, the exception thrown from the call to throw "Error" does not propagate into the parent scope (which would prevent the console.log statement from executing):

var e = document.createEvent("Event");
e.initEvent("myevent", false, false);
var target = document.createElement("div");
target.addEventListener("myevent", function () {
   throw "Error";
});
target.dispatchEvent(e); // Causes the event listener to throw an exception...
// The previously thrown exception doesn't affect the code that follows:
console.log("Exceptions? No problem");

As the next step, the event object MUST complete one or more event phases. This specification defines three event phases: capture phase, target phase and bubble phase. Event objects complete these phases in the specified order using the partial propagation paths as defined below. A phase MUST be skipped if it is not supported, or if the event object's propagation has been stopped. For example, if the Event.bubbles attribute is set to false, the bubble phase will be skipped, and if Event.stopPropagation() has been called prior to the dispatch, all phases MUST be skipped.

  1. The capture phase: The event object MUST propagate through the target's ancestors from the Window to the target's parent. This phase is also known as the capturing phase. Event listeners registered for this phase MUST handle the event before it reaches its target.
  2. The target phase: The event object MUST arrive at the event object's event target. This phase is also known as the at-target phase. Event listeners registered for this phase MUST handle the event once it has reached its target. If the event type indicates that the event MUST NOT bubble, the event object MUST halt after completion of this phase.
  3. The bubble phase: The event object propagates through the target's ancestors in reverse order, starting with the target's parent and ending with the Window. This phase is also known as the bubbling phase. Event listeners registered for this phase MUST handle the event after it has reached its target.

Implementations MUST let event objects accomplish an event phase by applying the following steps while there are pending event targets in the partial propagation path for this phase and the event object's propagation has not been stopped through Event.stopPropagation().

First, the implementation MUST determine the current target. This MUST be the next pending event target in the partial propagation path, starting with the first. From the perspective of an event listener this MUST be the event target the listener has been registered on.

Next, the implementation MUST determine the current target's candidate event listeners. This MUST be the list of all event listeners that have been registered on the current target in their order of registration. [HTML5] defines the ordering of listeners registered through event handler attributes. Once determined, the candidate event listeners MUST NOT be changed. Adding or removing listeners does not affect the current target's candidate event listeners.

Finally, the implementation MUST process all candidate event handlers in order and trigger each handler if all the following conditions are met:

  • The event object's immediate propagation has not been stopped.
  • The listener has been registered for this event phase.
  • The listener has been registered for this event type.

In the production of the propagation path, the event propagates from the Window to the document object during the capture phase, and from the document object to the Window during the bubble phase.

After an event completes all the phases of its propagation path, its Event.currentTarget MUST be set to null and the Event.eventPhase MUST be set to 0 (NONE). All other attributes of the Event (or interface derived from Event) are unchanged (including the Event.target attribute, which MUST continue to reference the event target).

The model defined above MUST be applied regardless of the specific event flow associated with an event target. Each event flow MUST define how the propagation path MUST be determined and which event phases are supported. The DOM event flow is an application of this model: the propagation path for a Node object MUST be determined by its Node.parentNode chain, and if applicable, the document's containing Window. All events accomplish the capture and target phases. Whether an event accomplishes the bubble phase MUST be defined individually for each event type. An alternate application of this model can be found in [DOM3 Load and Save].

Implementations of the DOM event model MUST be reentrant. Event listeners MAY perform actions that cause additional events to be dispatched. Such events are handled in a synchronous manner, the event propagation that causes the event listener to be triggered MUST resume only after the event dispatch of the new event is completed.

3.2 Default actions and cancelable events

Events are typically dispatched by the implementation as a result of a user action, in response to the completion of a task, or to signal progress during asynchronous activity (such as a network request). Some events can be used to control the behavior that the implementation MAY take next (or undo an action that the implementation already took). Events in this category are said to be cancelable and the behavior they cancel is called their default action. Cancelable event objects can be associated with one or more default actions. To cancel an event, call the Event.preventDefault() method.

A mousedown event is dispatched immediately after the user presses down a button on a pointing device (typically a mouse). One possible default action taken by the implementation is to set up a state machine that allows the user to drag images or select text. The default action depends on what happens next — for example, if the user's pointing device is over text, a text selection might begin. If the user's pointing device is over an image, then an image-drag action could begin. Preventing the default action of a mousedown event prevents these actions from occuring.

Default actions SHOULD be performed after the event dispatch has been completed, but in exceptional cases MAY also be performed immediately before the event is dispatched.

The default action associated with the click event on <input type="checkbox"> elements toggles the checked IDL attribute value of that element. If the click event's default action is cancelled, then the value is restored to its former state.

When an event is canceled, then the conditional default actions associated with the event MUST be skipped (or as mentioned above, if the default actions are carried out before the dispatch, their effect MUST be undone). Whether an event object is cancelable MUST be indicated by the Event.cancelable attribute. Event.preventDefault() stops all related default actions of an event object. The Event.defaultPrevented attribute indicates whether an event has already been canceled (e.g., by a prior event listener). If the DOM application itself initiated the dispatch, then the return value of the EventTarget.dispatchEvent() method indicates whether the event object was cancelled.

Authoring Note: Many implementations additionally interpret an event listener's return value, such as the value false, to mean that the default action of cancelable events will be cancelled (though window.onerror handlers are cancelled by returning true).

Authoring Note: Some cancelable events might not have any observable default actions. For example, the mousemove event.

This specification does not offer features to programatically query if an event object has any default action associated with it, or to associate new default actions with an event object. Other specifications SHOULD define what default actions, if any, are associated with certain event objects. Further, implementations MAY associate default actions with events as necessary and appropriate for that implementation.

As an example, one implementation might scroll a document view by a certain amount as the default action of a wheel event, while another implementation might instead zoom the document as its default action.

3.3 Synchronous and asynchronous events

Events MAY be dispatched either synchronously or asynchronously.

Events which are synchronous (sync events) MUST be treated as if they are in a virtual queue in a first-in-first-out model, ordered by sequence of temporal occurrence with respect to other events, to changes in the DOM, and to user interaction. Each event in this virtual queue MUST be delayed until the previous event has completed its propagation behavior, or been canceled. Some sync events are driven by a specific device or process, such as mouse button events. These events are governed by the event order algorithms defined for that set of events, and a user agent MUST dispatch these events in the defined order.

A user double-clicks a passage of text to select a word, then presses the 'Delete' key to erase the word, triggering the following synchronous sequence of events: mousedown, mouseup, click, mousedown, mouseup, click, dblclick, select, keydown, beforeinput, input, keyup. Each of these events are fired in the sequence initiated by the user's actions.

Events which are asynchronous (async events) MAY be dispatched as the results of the action are completed, with no relation to other events, to other changes in the DOM, nor to user interaction.

During loading of a document, an inline script element is parsed and executed. The load event is queued to be fired asynchronously at the script element. However, because it is an async event, its order with relation to other synchronous events fired during document load (such as the DOMContentLoaded event from HTML5) is not guaranteed.

3.3.1 Event order and event loops

Most events take place in a sequential context. [HTML5] defines its event operations in terms of an event loop mechanism, in which events of all types are fed into different task queues. This specification does not define events in terms of this event loop mechanism, but it is compatible with this mechanism. Instead, this specification defines several operation-specific event orders.

Using the terminology of HTML5, each independent device, such as a mouse or keyboard, SHOULD be treated as a task source which feeds into the appropriate task queue, in the order defined by the event order associated with that device. Each operation, such as a focus change or composition input, also acts as a task source for the appropriate task queue. The resolution of these event loops is handled in a manner conforming to the host language, such as HTML [HTML5].

Authoring Note: Certain events, such as hotkeys or control keys pressed in a certain sequence, can be swallowed by the operating system or the application, interrupting the expected event order.

3.4 Trusted events

Events that are generated by the user agent, either as a result of user interaction, or as a direct result of changes to the DOM, are trusted by the user agent with privileges that are not afforded to events generated by script through the DocumentEvent.createEvent("Event") method, modified using the Event.initEvent() method, or dispatched via the EventTarget.dispatchEvent() method. The isTrusted attribute of trusted events has a value of true, while untrusted events have a isTrusted attribute value of false.

Most untrusted events SHOULD NOT trigger default actions, with the exception of the click event. This event always triggers the default action, even if the isTrusted attribute is false (this behavior is retained for backward-compatibility). All other untrusted events MUST behave as if the Event.preventDefault() method had been called on that event.

3.5 Activation triggers and behavior

Certain event targets (such as a link or button element) MAY have associated activation behavior (such a following a link) that implementations perform in response to an activation trigger (such as clicking a link).

A host language SHOULD indicate which, if any, elements have activation behavior, describe appropriate activation triggers, and define the result of that activation behavior. An implementation which supports a host language SHOULD initiate these activation behavior when the associated activation trigger occurs.

Both HTML and SVG have an <a> element which indicates a link. Relevant activation triggers for an <a> element are a click event on the text or image content of the <a> element, or a keydown event with a key attribute value of 'Enter' key when the <a> element has focus. The activation behavior for an <a> element is normally to change the content of the window to the content of the new document, in the case of external links, or to reposition the current document relative to the new anchor, in the case of internal links.

An activation trigger is a user action or an event which indicates to the implementation that an activation behavior SHOULD be initiated. User-initiated activation triggers include clicking a mouse button on an activatable element, pressing the 'Enter' key when an activatable element has focus, or pressing a key that is somehow linked to an activatable element (a hotkey or access key) even when that element does not have focus. Event-based activation triggers MAY include timer-based events that activate an element at a certain clock time or after a certain time period has elapsed, progress events after a certain action has been completed, or many other condition-based or state-based events.

In some cases, a host language MAY define attributes or even attribute values which add to or change the native activation trigger or activation behavior of an element. For example, ARIA [ARIA] defines values for the role attribute that add semantics to the element to which it is applied, for purposes of enhanced accessibility. In such cases, if the host language does not explicitly define the activation trigger or activation behavior, the content author MUST provide the mechanics of the activation trigger (via an event listener) or activation behavior (such as calling an ECMAScript function) for that element when applying that attribute or attribute value.

3.5.1 Activation event synthesis

If the instance of the activation trigger is not an event of event type click (that is, when it does not result from a user's activation of a button or link using a mouse or equivalent pointing device), the implementation MUST synthesize and dispatch an event of event type click as one of the default actions of that activation trigger. The value of the Event.target MUST be set to the event target (normally, the currently focused element), and the event MUST simulate a left click (i.e., the MouseEvent.button attribute value MUST be 0, and the MouseEvent.buttons attribute value MUST be 1). Other context information of such a simulated click event is implementation dependent, but for historical purposes, the interface for the click event MUST be the MouseEvent interface, regardless of the actual device used to activate the element. Preventing the default action of the activation trigger, such as with the Event.preventDefault(), MUST stop the initiation of the activation behavior.

When a user activates a hyperlink using a keyboard, such as by focusing the hyperlink element and pressing the 'Enter' or ' ' key, a click event would be dispatched as the default action of the respective keydown event.

Implementations MUST dispatch the synthesized click event as described above even if they do not normally dispatch such an event (e.g., when activation is requested by a voice command, since this specification does not address event types for voice input).

Note: The activation of an event target is device dependent, but is also application dependent, e.g., a link in a document can be activated using a mouse click or a mouse double click.

3.5.2 Activation event order

Activation triggers and behavior can be defined in part by the events which are dispatched in a set order relative to one another. The following is the typical sequence of events for an element activated by a pointing device (with only pertinent events listed):

  Event NameNotes
1. click  
    All default actions, including the activation behavior

The following is the typical sequence of events when a focused element is activated by a key event (with only pertinent events listed):

  Event NameNotes
1. keydown MUST be a key which can activate the element, such as the 'Enter' or ' ' key, or the element is not activated
2. click default action; synthesized; isTrusted="true"
    All default actions, including the activation behavior

3.6 Event exceptions

This section is informative.

Event operations can throw a DOMException as specified in their method descriptions.

Note: The exception EventException introduced in DOM Level 2 is removed in this specification as part of this specification's normative support of Web IDL. EventException formerly defined an exception code UNSPECIFIED_EVENT_TYPE_ERR which is replaced in this specification by the use of a DOMException of type InvalidStateError.

The following DOMException types are used in this specification.

TypeDescription
InvalidStateError Thrown when the Event.type was not specified by initializing the event before dispatchEvent was called. Also thrown when the Event object provided to dispatchEvent is already being dispatched.
NotSupportedError Thrown when DocumentEvent.createEvent() is passed an Event interface that the implementation does not support.

4. Basic Event Interfaces

The basic event interfaces defined in DOM4 [DOM4] are fundamental to DOM Level 3 Events. These basic event interfaces MUST always be supported by the implementation:

  • The Event interface and its following constants, methods and attributes:
    • NONE constant
    • CAPTURING_PHASE constant
    • AT_TARGET constant
    • BUBBLING_PHASE constant
    • type attribute
    • target attribute
    • currentTarget attribute
    • eventPhase attribute
    • bubbles attribute
    • cancelable attribute
    • timeStamp attribute
    • defaultPrevented attribute
    • isTrusted attribute
    • stopPropagation() method
    • stopImmediatePropagation() method
    • preventDefault() method
    • initEvent() method
  • The CustomEvent interface and its following method and attribute:
    • initCustomEvent() method
    • detail attribute
  • The EventTarget interface and its following methods:
    • addEventListener() method
    • removeEventListener() method
    • dispatchEvent() method
  • The EventListener interface and its handleEvent method
  • The Document interface's createEvent method

The event types defined in this specification derive from these basic interfaces, and MUST inherit all of the attributes, methods, and constants of the interfaces they derive from.

The following chart describes the inheritance structure of interfaces defined in this specification.

Graphical representation of the DOM3 Events interface inheritance
Fig. 2 Graphical representation of the DOM3 Events interface inheritance

4.1 List of Event Types

Each event MUST be associated with a type, called event type and available as the type attribute on the event object. The event type MUST be of type DOMString.

Depending on the level of DOM support, or the devices used for display (e.g., screen) or interaction (e.g., mouse, keyboard, touch screen, or voice), these event types can be generated by the implementation. When used with an [XML 1.0] or [HTML5] application, the specifications of those languages MAY restrict the semantics and scope (in particular the possible event targets) associated with an event type. Refer to the specification defining the language used in order to find those restrictions or to find event types that are not defined in this document.

The following table provides an informative summary of the event types defined in this specification.

Event TypeSync / AsyncBubbling phaseTrusted event target typesDOM interfaceCancelableDefault Action
abort Sync No Window, Element Event No None
beforeinput Sync Yes Element InputEvent Yes Update the DOM element
blur Sync No Window, Element FocusEvent No None
click Sync Yes Element MouseEvent Yes Varies: for targets with an associated activation behavior, executes the activation behavior; for focusable targets, gives the element focus.
compositionstart Sync Yes Element CompositionEvent Yes Show a text composition system candidate window
compositionupdate Sync Yes Element CompositionEvent No None
compositionend Sync Yes Element CompositionEvent No None
dblclick Sync Yes Element MouseEvent No Varies: for targets with an associated activation behavior, executes the activation behavior; for focusable targets, gives the element focus; for selectable targets, selects part or all of the element's content.
error Async No Window, Element Event No None
focus Sync No Window, Element FocusEvent No None
focusin Sync Yes Window, Element FocusEvent No None
focusout Sync Yes Window, Element FocusEvent No None
input Sync Yes Element InputEvent No None
keydown Sync Yes Element KeyboardEvent Yes Varies: beforeinput and input events; launch text composition system; blur and focus events; keypress event; activation behavior; other event
keyup Sync Yes Element KeyboardEvent Yes None
load Async No Window, Document, Element Event No None
mousedown Sync Yes Element MouseEvent Yes Varies: start a drag/drop operation; start a text selection; start a scroll/pan interaction (in combination with the middle mouse button, if supported)
mouseenter Sync No Element MouseEvent No None
mouseleave Sync No Element MouseEvent No None
mousemove Sync Yes Element MouseEvent Yes None
mouseout Sync Yes Element MouseEvent Yes None
mouseover Sync Yes Element MouseEvent Yes None
mouseup Sync Yes Element MouseEvent Yes Invoke a context menu (in combination with the right mouse button, if supported)
resize Sync No Window, Element UIEvent No None
scroll Async No / Yes Document, Element UIEvent No None
select Sync Yes Element Event No None
unload Sync No Window, Document, Element Event No None
wheel Async Yes Element WheelEvent Yes Scroll (or zoom) the document

For a list of events which are deprecated in this specification, see the Legacy Event Types appendix at the end of this document.

The following is one way to interpret the above tables: the load event will trigger event listeners attached on Element nodes for that event and on the capture and target phases. This event is not cancelable. If an event listener for the load event is attached to a node other than Window, Document, or Element nodes, or if it is attached to the bubbling phase only, this event listener would not be triggered.

Note: Don't interpret the above tables as definitive for the listed event types. For example, the load event is used in other specifications, for example, in XMLHttpRequest. Similarly, dispatchEvent can be used to dispatch untrusted events to listeners on any object that also implements EventTarget.

Note: The event objects associated with the event types described above contain additional context information--refer to the description of the DOM interfaces for further information.

5. Event Types

The DOM Event Model allows a DOM implementation to support multiple modules of events. The model has been designed to allow addition of new event modules in the future. This document does not attempt to define all possible events. For purposes of interoperability, the DOM defines a module of user interface events including lower level device dependent events and a module of document mutation events.

5.1 User Interface Event Types

The User Interface event module contains basic event types associated with user interfaces and document manipulation.

5.1.1 Interface UIEvent

Introduced in DOM Level 2

The UIEvent interface provides specific contextual information associated with User Interface events.

To create an instance of the UIEvent interface, use the DocumentEvent.createEvent("UIEvent") method call.

[Constructor(DOMString type, optional UIEventInit eventInitDict)]
interface UIEvent : Event {
    readonly    attribute WindowProxy? view;
    readonly    attribute long         detail;
};
5.1.1.1 Attributes
detail of type long, readonly

Specifies some detail information about the Event, depending on the type of event.

The un-initialized value of this attribute MUST be 0.

view of type WindowProxy, readonly , nullable

The view attribute identifies the Window from which the event was generated.

The un-initialized value of this attribute MUST be null.

dictionary UIEventInit : EventInit {
    WindowProxy? view = null;
    long         detail = 0;
};
5.1.1.2 Dictionary UIEventInit Members
detail of type long, defaulting to 0

This value is initialized to a number that is application-specific.

view of type WindowProxy, nullable, defaulting to null

Should be initialized to the Window object of the global environment in which this event will be dispatched. If this event will be dispatched to an element, the view property should be set to the Window object containing the element's ownerDocument.

The User Interface event types are listed below. Some of these events use the UIEvent interface if generated from a user interface, but the Event interface otherwise, as detailed in each event.

load
Type load
Interface UIEvent if generated from a user interface, Event otherwise.
Sync / Async Async
Bubbles No
Trusted Targets Window, Document, Element
Cancelable No
Default action None
Context
(trusted events)

A user agent MUST dispatch this event when the DOM implementation finishes loading the resource (such as the document) and any dependent resources (such as images, style sheets, or scripts). Dependent resources that fail to load MUST NOT prevent this event from firing if the resource that loaded them is still accessible via the DOM. If this event type is dispatched, implementations are REQUIRED to dispatch this event at least on the Document node.

Note: For legacy reasons, load events for resources inside the document (e.g., images) do not include the Window in the propagation path in HTML implementations. See [HTML5] for more information.

unload
Type unload
Interface UIEvent if generated from a user interface, Event otherwise.
Sync / Async Sync
Bubbles No
Trusted Targets Window, Document, Element
Cancelable No
Default action None
Context
(trusted events)

A user agent MUST dispatch this event when the DOM Implementation removes from the environment the resource (such as the document) or any dependent resources (such as images, style sheets, scripts). The document MUST be unloaded after the dispatch of this event type. If this event type is dispatched, implementations are REQUIRED to dispatch this event at least on the Document node.

abort
Type abort
Interface UIEvent if generated from a user interface, Event otherwise.
Sync / Async Sync
Bubbles No
Trusted Targets Window, Element
Cancelable No
Default action None
Context
(trusted events)

A user agent MUST dispatch this event when the loading of a resource has been aborted, such as by a user canceling the load while it is still in progress.

error
Type error
Interface UIEvent if generated from a user interface, Event otherwise.
Sync / Async Async
Bubbles No
Trusted Targets Window, Element
Cancelable No
Default action None
Context
(trusted events)

A user agent MUST dispatch this event when a resource failed to load, or has been loaded but cannot be interpreted according to its semantics, such as an invalid image, a script execution error, or non-well-formed XML.

select
Type select
Interface UIEvent if generated from a user interface, Event otherwise.
Sync / Async Sync
Bubbles Yes
Trusted Targets Element
Cancelable No
Default action None
Context
(trusted events)

A user agent MUST dispatch this event when a user selects some text. This event is dispatched after the selection has occurred.

This specification does not provide contextual information to access the selected text. Where applicable, a host language SHOULD define rules for how a user MAY select content (with consideration for international language conventions), at what point the select event is dispatched, and how a content author MAY access the user-selected content.

Note: In order to access to user-selected content, content authors will use native capabilities of the host languages, such as the Document.getSelection() method of the HTML Editing APIs [HTML Editing].

Note: The select event might not be available for all elements in all languages. For example, in [HTML5], select events can be dispatched only on form input and textarea elements. Implementations can dispatch select events in any context deemed appropriate, including text selections outside of form controls, or image or markup selections such as in SVG.

resize
Type resize
Interface UIEvent
Sync / Async Sync
Bubbles No
Trusted Targets Window, Element
Cancelable No
Default action None
Context
(trusted events)

A user agent MUST dispatch this event when a document view has been resized. This event type is dispatched after all effects for that occurrence of resizing of that particular event target have been executed by the user agent.

User agents which support continuous reflow of the document's layout during user-initiated resizing MUST dispatch this event synchronously after each reflow of the document.

The Window object SHOULD always be resizable. A host language MAY define certain elements to be resizable, and under what conditions (e.g., specific elements like <iframe>, or elements with particular characteristics like width and height). However, this specification does not define the behavior for elements.

Note: The resize event is distinct from the SVG zoom event types, though both can occur at the same time, or as the consequence of the same user action. In particular, browser font zooming or page zooming will not necessarily trigger a resize event.

Note: In previous DOM Events specifications, the resize event type was defined to have a bubbling phase, but for performance reasons, this was not implemented in most user agents, and this specification removes the bubbling phase for this event.

scroll
Type scroll
Interface UIEvent
Sync / Async Async
Bubbles No / Yes
Trusted Targets Document, Element
Cancelable No
Default action None
Context
(trusted events)

A user agent MUST dispatch this event when a document view or an element has been scrolled. This event type is dispatched after the scroll has occurred.

When dispatched on the Document element, this event type MUST bubble to the Window object.

5.2 Focus Event Types

Note: This interface and its associated event types and focus event order were designed in accordance to the concepts and guidelines defined in User Agent Accessibility Guidelines 2.0 [UAAG 2.0], with particular attention on the focus mechanism and the terms defined in the glossary entry for focus.

5.2.1 Interface FocusEvent

Introduced in DOM Level 3

The FocusEvent interface provides specific contextual information associated with Focus events.

To create an instance of the FocusEvent interface, use the DocumentEvent.createEvent("FocusEvent") method call. 

[Constructor(DOMString typeArg, optional FocusEventInit focusEventInitDict)]
interface FocusEvent : UIEvent {
    readonly    attribute EventTarget? relatedTarget;
};
5.2.1.1 Attributes
relatedTarget of type EventTarget, readonly , nullable

Used to identify a secondary EventTarget related to a Focus event, depending on the type of event.

For security reasons with nested browsing contexts, when tabbing into or out of a nested context, the relevant EventTarget SHOULD be null.

The un-initialized value of this attribute MUST be null.

dictionary FocusEventInit : UIEventInit {
    EventTarget? relatedTarget = null;
};
5.2.1.2 Dictionary FocusEventInit Members
relatedTarget of type EventTarget, nullable, defaulting to null

The relatedTarget should be initialized to the element whose bounds the mouse pointer just left (in the case of a mouseover or mouseenter event) or the element whose bounds the mouse pointer is entering (in the case of a mouseout or mouseleave or focusout event). For other events, this value need not be assigned (and will default to null).

5.2.2 Focus Event Order

The focus events defined in this specification occur in a set order relative to one another. The following is the typical sequence of events when a focus is shifted between elements (this order assumes that no element is initially focused):

  Event NameNotes
    User shifts focus
1. focusin Sent before first target element receives focus
2. focus Sent after first target element receives focus
    User shifts focus
3. focusout Sent before first target element loses focus
4. focusin Sent before second target element receives focus
5. blur Sent after first target element loses focus
6. focus Sent after second target element receives focus

Note: This specification does not define the behavior of focus events when interacting with methods such as focus() or blur(). See the relevant specifications where those methods are defined for such behavior.

5.2.3 Document Focus and Focus Context

This event module includes event types for notification of changes in document focus. There are three distinct focus contexts that are relevant to this discussion:

  • The operating system focus context which MAY be on one of many different applications currently running on the computer. One of these applications with focus can be a browser.
  • When the browser has focus, the user can switch (such as with the tab key) the application focus context among the different browser user interface fields (e.g., the Web site location bar, a search field, etc.). One of these user interface fields can be the document being shown in a tab.
  • When the document itself has focus, the document focus context can be set to any of the focusable elements in the document.

The event types defined in this specification deal exclusively with document focus, and the event target identified in the event details MUST only be part of the document or documents in the window, never a part of the browser or operating system, even when switching from one focus context to another.

Normally, a document always has a focused element (even if it is the document element itself) and a persistent focus ring. When switching between focus contexts, the document's currently focused element and focus ring normally remain in their current state. For example, if a document has three focusable elements, with the second element focused, when a user changes operating system focus to another application and then back to the browser, the second element will still be focused within the document, and tabbing will change the focus to the third element. A host language MAY define specific elements which might receive focus, the conditions under which an element MAY receive focus, the means by which focus MAY be changed, and the order in which the focus changes. For example, in some cases an element might be given focus by moving a pointer over it, while other circumstances might require a mouse click. Some elements might not be focusable at all, and some might be focusable only by special means (clicking on the element), but not by tabbing to it. Documents MAY contain multiple focus rings. Other specifications MAY define a more complex focus model than is described in this specification, including allowing multiple elements to have the current focus.

The Focus event types are listed below.

blur
Type blur
Interface FocusEvent
Sync / Async Sync
Bubbles No
Trusted Targets Window, Element
Cancelable No
Default action None
Context
(trusted events)

A user agent MUST dispatch this event when an event target loses focus. The focus MUST be taken from the element before the dispatch of this event type. This event type is similar to focusout, but is dispatched after focus is shifted, and does not bubble.

focus
Type focus
Interface FocusEvent
Sync / Async Sync
Bubbles No
Trusted Targets Window, Element
Cancelable No
Default action None
Context
(trusted events)

A user agent MUST dispatch this event when an event target receives focus. The focus MUST be given to the element before the dispatch of this event type. This event type is similar to focusin, but is dispatched after focus is shifted, and does not bubble.

focusin
Type focusin
Interface FocusEvent
Sync / Async Sync
Bubbles Yes
Trusted Targets Window, Element
Cancelable No
Default action None
Context
(trusted events)

A user agent MUST dispatch this event when an event target is about to receive focus. This event type MUST be dispatched before the element is given focus. The event target MUST be the element which is about to receive focus. This event type is similar to focus, but is dispatched before focus is shifted, and does bubble.

Note: When using this event type, the content author can use the event's FocusEvent.relatedTarget attribute (or a host-language-specific method or means) to get the currently focused element before the focus shifts to the next focus event target, thus having access to both the element losing focus and the element gaining focus without the use of the blur or focusout event types.

focusout
Type focusout
Interface FocusEvent
Sync / Async Sync
Bubbles Yes
Trusted Targets Window, Element
Cancelable No
Default action None
Context
(trusted events)

A user agent MUST dispatch this event when an event target is about to lose focus. This event type MUST be dispatched before the element loses focus. The event target MUST be the element which is about to lose focus. This event type is similar to blur, but is dispatched before focus is shifted, and does bubble.

5.3 Mouse Event Types

The mouse event module originates from the [HTML 4.01] onclick, ondblclick, onmousedown, onmouseup, onmouseover, onmousemove, and onmouseout attributes. This event module is specifically designed for use with pointing input devices, such as a mouse or a trackball.

5.3.1 Interface MouseEvent

Introduced in DOM Level 2, modified in DOM Level 3

The MouseEvent interface provides specific contextual information associated with Mouse events.

In the case of nested elements, mouse events are always targeted at the most deeply nested element.

Note: Ancestors of the targeted element can use event bubbling to obtain notifications of mouse events which occur within their descendent elements.

To create an instance of the MouseEvent interface, use the DocumentEvent.createEvent("MouseEvent") method call.

Note: When initializing MouseEvent objects using initMouseEvent, implementations can use the client coordinates clientX and clientY for calculation of other coordinates (such as target coordinates exposed by DOM Level 0 implementations or other proprietary attributes, e.g., pageX). 

[Constructor(DOMString typeArg, optional MouseEventInit mouseEventInitDict)]
interface MouseEvent : UIEvent {
    readonly    attribute long           screenX;
    readonly    attribute long           screenY;
    readonly    attribute long           clientX;
    readonly    attribute long           clientY;
    readonly    attribute boolean        ctrlKey;
    readonly    attribute boolean        shiftKey;
    readonly    attribute boolean        altKey;
    readonly    attribute boolean        metaKey;
    readonly    attribute short          button;
    readonly    attribute EventTarget?   relatedTarget;
    // Introduced in DOM Level 3
    readonly    attribute unsigned short buttons;
    boolean getModifierState (DOMString keyArg);
};
5.3.1.1 Attributes
altKey of type boolean, readonly

Refer to the KeyboardEvent.altKey attribute.

The un-initialized value of this attribute MUST be false.

button of type short, readonly

During mouse events caused by the depression or release of a mouse button, button MUST be used to indicate which pointer device button changed state.

The value of the MouseEvent.button attribute MUST be as follows:

  • 0 MUST indicate the primary button of the device (in general, the left button or the only button on single-button devices, used to activate a user interface control or select text) or the un-initialized value.
  • 1 MUST indicate the auxiliary button (in general, the middle button, often combined with a mouse wheel).
  • 2 MUST indicate the secondary button (in general, the right button, often used to display a context menu).

Some pointing devices provide or simulate more button states, and values higher than 2 or lower than 0 MAY be used to represent such buttons.

Note: The value of button is not updated for events not caused by the depression/release of a mouse button. In these scenarios, take care not to interpret the value 0 as the left button, but rather as the un-initialized value.

Authoring Note: Some default actions related to events such as mousedown and mouseup depend on the specific mouse button in use.

The un-initialized value of this attribute MUST be 0.

buttons of type unsigned short, readonly

During any mouse events, buttons MUST be used to indicate which combination of mouse buttons are currently being pressed, expressed as a bitmask.

Note: Though similarly named, the values for the buttons attribute and the button attribute are very different. The value of button is assumed to be valid during mousedown / mouseup event handlers, whereas the buttons attribute reflects the state of the mouse's buttons for any trusted MouseEvent object (while it is being dispatched), because it can represent the "no button currently active" state (0).

The value of the MouseEvent.buttons attribute MUST be as follows:

  • 0 MUST indicate no button is currently active.
  • 1 MUST indicate the primary button of the device (in general, the left button or the only button on single-button devices, used to activate a user interface control or select text).
  • 2 MUST indicate the secondary button (in general, the right button, often used to display a context menu), if present.
  • 4 MUST indicate the auxiliary button (in general, the middle button, often combined with a mouse wheel).

Some pointing devices provide or simulate more buttons. To represent such buttons, the value MUST be doubled for each successive button (in the binary series 8, 16, 32, ... ).

Note: Because the sum of any set of button values is a unique number, a content author can use a bitwise operation to determine how many buttons are currently being pressed and which buttons they are, for an arbitrary number of mouse buttons on a device. For example, the value 3 indicates that the left and right button are currently both pressed, while the value 5 indicates that the left and middle button are currently both pressed.

Authoring Note: Some default actions related to events such as mousedown and mouseup depend on the specific mouse button in use.

The un-initialized value of this attribute MUST be 0.

clientX of type long, readonly

The horizontal coordinate at which the event occurred relative to the viewport associated with the event.

The un-initialized value of this attribute MUST be 0.

clientY of type long, readonly

The vertical coordinate at which the event occurred relative to the viewport associated with the event.

The un-initialized value of this attribute MUST be 0.

ctrlKey of type boolean, readonly

Refer to the KeyboardEvent.ctrlKey attribute.

The un-initialized value of this attribute MUST be false.

metaKey of type boolean, readonly

Refer to the KeyboardEvent.metaKey attribute.

The un-initialized value of this attribute MUST be false.

relatedTarget of type EventTarget, readonly , nullable

Used to identify a secondary EventTarget related to a UI event, depending on the type of event.

The un-initialized value of this attribute MUST be null.

screenX of type long, readonly

The horizontal coordinate at which the event occurred relative to the origin of the screen coordinate system.

The un-initialized value of this attribute MUST be 0.

screenY of type long, readonly

The vertical coordinate at which the event occurred relative to the origin of the screen coordinate system.

The un-initialized value of this attribute MUST be 0.

shiftKey of type boolean, readonly

Refer to the KeyboardEvent.shiftKey attribute.

The un-initialized value of this attribute MUST be false.

5.3.1.2 Methods
getModifierState

Introduced in DOM Level 3

Queries the state of a modifier using a key value. See Modifier keys for a list of valid (case-sensitive) arguments to this method.

Returns true if it is a modifier key and the modifier is activated, false otherwise.

ParameterTypeNullableOptionalDescription
keyArg DOMString ✘ ✘

Refer to the KeyboardEvent.getModifierState() method for a description of this parameter.
Return type: boolean
dictionary MouseEventInit : SharedKeyboardAndMouseEventInit {
    long           screenX = 0;
    long           screenY = 0;
    long           clientX = 0;
    long           clientY = 0;
    short          button = 0;
    unsigned short buttons = 0;
    EventTarget?   relatedTarget = null;
};
5.3.1.3 Dictionary MouseEventInit Members
button of type short, defaulting to 0

Initializes the button attribute of the MouseEvent object to a number representing the desired state of the button(s) of the mouse.

Note: The value 0 is used to represent the primary mouse button, 1 is used to represent the auxiliary/middle mouse button, and 2 to represent the right mouse button. Numbers greater than 2 are also possible, but are not specified in this document.

buttons of type unsigned short, defaulting to 0

Initializes the buttons attribute of the MouseEvent object to a number representing one or more of the button(s) of the mouse that are to be considered active.

Note: The buttons attribute is a bit-field. If a mask value of 1 is true when applied to the value of the bit field, then the primary mouse button is down. If a mask value of 2 is true when applied to the value of the bit field, then the right mouse button is down. If a mask value of 4 is true when applied to the value of the bit field, then the auxiliary/middle button is down.

In JavaScript, to initialize the buttons attribute as if the right (2) and middle button (4) were being pressed simultaneously, the buttons value can be assigned as either:
{ buttons: 2 | 4 }
or:
{ buttons: 6 }

clientX of type long, defaulting to 0

See clientY (substituting "horizontal" for "vertical").

clientY of type long, defaulting to 0

Initializes the clientY attribute of the MouseEvent object to the desired vertical position of the mouse pointer relative to the client window of the user's browser.

Initializing the event object to the given mouse position must not move the user's mouse pointer to the initialized position.

relatedTarget of type EventTarget, nullable, defaulting to null

The relatedTarget should be initialized to the element whose bounds the mouse pointer just left (in the case of a mouseover or mouseenter event) or the element whose bounds the mouse pointer is entering (in the case of a mouseout or mouseleave or focusout event). For other events, this value need not be assigned (and will default to null).

screenX of type long, defaulting to 0

See screenY (substituting "horizontal" for "veritcal").

screenY of type long, defaulting to 0

Initializes the screenY attribute of the MouseEvent object to the desired vertical relative position of the mouse pointer on the user's screen.

Initializing the event object to the given mouse position must not move the user's mouse pointer to the initialized position.

Implementations MUST maintain the current click count when generating mouse events. This MUST be a non-negative integer indicating the number of consecutive clicks of a pointing device button within a specific time. The delay after which the count resets is specific to the environment configuration.

5.3.2 Shared MouseEvent and KeyboardEvent initializers

The MouseEvent and KeyboardEvent interfaces share a set of keyboard modifier attributes and support a mechanism for retrieving additional modifier states. The following dictionary enables authors to initialize keyboard modifier attributes of the MouseEvent and KeyboardEvent interfaces, as well as the additional modifier states queried via KeyboardEvent.getModifierState().

dictionary SharedKeyboardAndMouseEventInit : UIEventInit {
    boolean ctrlKey = false;
    boolean shiftKey = false;
    boolean altKey = false;
    boolean metaKey = false;
    boolean keyModifierStateAltGraph = false;
    boolean keyModifierStateCapsLock = false;
    boolean keyModifierStateFn = false;
    boolean keyModifierStateFnLock = false;
    boolean keyModifierStateHyper = false;
    boolean keyModifierStateNumLock = false;
    boolean keyModifierStateOS = false;
    boolean keyModifierStateScrollLock = false;
    boolean keyModifierStateSuper = false;
    boolean keyModifierStateSymbol = false;
    boolean keyModifierStateSymbolLock = false;
};
5.3.2.1 Dictionary SharedKeyboardAndMouseEventInit Members
altKey of type boolean, defaulting to false

Initializes the altKey attribute of the MouseEvent or KeyboardEvent objects to true if the 'Alt' (alternative) (or 'Option') key modifier is to be considered active, false otherwise.

When true, implementations must also initialize the event object's key modifier state such that calls to the MouseEvent.getModifierState() or KeyboardEvent.getModifierState() when provided with the parameter 'Alt' must return true.

ctrlKey of type boolean, defaulting to false

Initializes the altKey attribute of the MouseEvent or KeyboardEvent objects to true if the 'Control' (control) key modifier is to be considered active, false otherwise.

When true, implementations must also initialize the event object's key modifier state such that calls to the MouseEvent.getModifierState() or KeyboardEvent.getModifierState() when provided with either the parameter 'Control' or the parameter 'Accel' must return true.

keyModifierStateAltGraph of type boolean, defaulting to false

Initializes the event object's key modifier state such that calls to the MouseEvent.getModifierState() or KeyboardEvent.getModifierState() when provided with the parameter 'AltGraph' must return true.

keyModifierStateCapsLock of type boolean, defaulting to false

Initializes the event object's key modifier state such that calls to the MouseEvent.getModifierState() or KeyboardEvent.getModifierState() when provided with the parameter 'CapsLock' must return true.

keyModifierStateFn of type boolean, defaulting to false

Initializes the event object's key modifier state such that calls to the MouseEvent.getModifierState() or KeyboardEvent.getModifierState() when provided with the parameter 'Fn' must return true.

keyModifierStateFnLock of type boolean, defaulting to false

Initializes the event object's key modifier state such that calls to the MouseEvent.getModifierState() or KeyboardEvent.getModifierState() when provided with the parameter 'FnLock' must return true.

keyModifierStateHyper of type boolean, defaulting to false

Initializes the event object's key modifier state such that calls to the MouseEvent.getModifierState() or KeyboardEvent.getModifierState() when provided with the parameter 'Hyper' must return true.

keyModifierStateNumLock of type boolean, defaulting to false

Initializes the event object's key modifier state such that calls to the MouseEvent.getModifierState() or KeyboardEvent.getModifierState() when provided with the parameter 'NumLock' must return true.

keyModifierStateOS of type boolean, defaulting to false

Initializes the event object's key modifier state such that calls to the MouseEvent.getModifierState() or KeyboardEvent.getModifierState() when provided with the parameter 'OS' must return true.

keyModifierStateScrollLock of type boolean, defaulting to false

Initializes the event object's key modifier state such that calls to the MouseEvent.getModifierState() or KeyboardEvent.getModifierState() when provided with the parameter 'ScrollLock' must return true.

keyModifierStateSuper of type boolean, defaulting to false

Initializes the event object's key modifier state such that calls to the MouseEvent.getModifierState() or KeyboardEvent.getModifierState() when provided with the parameter 'Super' must return true.

keyModifierStateSymbol of type boolean, defaulting to false

Initializes the event object's key modifier state such that calls to the MouseEvent.getModifierState() or KeyboardEvent.getModifierState() when provided with the parameter 'Symbol' must return true.

keyModifierStateSymbolLock of type boolean, defaulting to false

Initializes the event object's key modifier state such that calls to the MouseEvent.getModifierState() or KeyboardEvent.getModifierState() when provided with the parameter 'SymbolLock' must return true.

metaKey of type boolean, defaulting to false

Initializes the metaKey attribute of the MouseEvent or KeyboardEvent objects to true if the 'Meta' key modifier is to be considered active, false otherwise.

When true, implementations must also initialize the event object's key modifier state such that calls to the MouseEvent.getModifierState() or KeyboardEvent.getModifierState() when provided with either the parameter 'Meta' or the parameter 'Accel' must return true.

shiftKey of type boolean, defaulting to false

Initializes the shiftKey attribute of the MouseEvent or KeyboardEvent objects to true if the 'Shift' key modifier is to be considered active, false otherwise.

When true, implementations must also initialize the event object's key modifier state such that calls to the MouseEvent.getModifierState() or KeyboardEvent.getModifierState() when provided with the parameter 'Shift' must return true.

5.3.3 Mouse Event Order

Certain mouse events defined in this specification MUST occur in a set order relative to one another. The following shows the event sequence that MUST occur when a pointing device's cursor is moved over an element:

  Event NameElementNotes
1. mousemove    
      Pointing device is moved into element A...
2. mouseover A  
3. mouseenter A  
4. mousemove A Multiple events
      Pointing device is moved out of element A...
5. mouseout A  
6. mouseleave A  

When a pointing device is moved into an element A, and then into a nested element B and then back out again, the following sequence of events MUST occur:

  Event NameElementNotes
1. mousemove    
      Pointing device is moved into element A...
2. mouseover A  
3. mouseenter A  
4. mousemove A Multiple events
      Pointing device is moved into nested element B...
5. mouseout A  
6. mouseover B  
7. mouseenter B  
8. mousemove B Multiple events
      Pointing device is moved from element B into A...
9. mouseout B  
10. mouseleave B  
11. mouseover A  
12. mousemove A Multiple events
      Pointing device is moved out of element A...
13. mouseout A  
14. mouseleave A  

Sometimes elements can be visually overlapped using CSS. In the following example, three elements labeled A, B, and C all have the same dimensions and absolute position on a web page. Element C is a child of B, and B is a child of A in the DOM:

Graphical representation of three stacked elements all on top of each other. The bottom element is labeled A and the top element is C
Fig. 3 Graphical representation of three stacked elements all on top of each other, with the pointing device moving over the stack.

When the pointing device is moved from outside the element stack to the element labeled C and then moved out again, the following series of events MUST occur:

  Event NameElementNotes
1. mousemove    
      Pointing device is moved into element C, the topmost element in the stack
2. mouseover C  
3. mouseenter A  
4. mouseenter B  
5. mouseenter C  
6. mousemove C Multiple events
      Pointing device is moved out of element C...
7. mouseout C  
8. mouseleave C  
9. mouseleave B  
10. mouseleave A  

Note: The mouseover/mouseout events are only fired once, while mouseenter/mouseleave events are fired three times (once to each element).

The following is the typical sequence of events when a button associated with a pointing device (e.g., a mouse button or trackpad) is pressed and released over an element:

  Event NameNotes
1. mousedown  
2. mousemove OPTIONAL, multiple events, some limits
3. mouseup  
4. click  
5. mousemove OPTIONAL, multiple events, some limits
6. mousedown  
7. mousemove OPTIONAL, multiple events, some limits
8. mouseup  
9. click  
10. dblclick  

Note: The lag time, degree, distance, and number of mousemove events allowed between the mousedown and mouseup events while still firing a click or dblclick event will be implementation-, device-, and platform-specific. This tolerance can aid users that have physical disabilities like unsteady hands when these users interact with a pointing device.

Each implementation will determine the appropriate hysteresis tolerance, but in general SHOULD fire click and dblclick events when the event target of the associated mousedown and mouseup events is the same element with no mouseout or mouseleave events intervening, and SHOULD fire click and dblclick events on the nearest common inclusive ancestor when the associated mousedown and mouseup event targets are different.

If a mousedown event was targeted at an HTML document's body element, and the corresponding mouseup event was targeted at the root element, then the click event will be dispatched to the root element, since it is the nearest common inclusive ancestor.

If the event target (e.g. the target element) is removed from the DOM during the mouse events sequence, the remaining events of the sequence MUST NOT be fired on that element.

If the target element is removed from the DOM as the result of a mousedown event, no events for that element will be dispatched for mouseup, click, or dblclick, nor any default activation events. However, the mouseup event will still be dispatched on the element that is exposed to the mouse after the removal of the initial target element. Similarly, if the target element is removed from the DOM during the dispatch of a mouseup event, the click and subsequent events will not be dispatched.

The Mouse event types are listed below. In the case of nested elements, mouse event types are always targeted at the most deeply nested element. Ancestors of the targeted element MAY use bubbling to obtain notification of mouse events which occur within its descendent elements.

click
Type click
Interface MouseEvent
Sync / Async Sync
Bubbles Yes
Trusted Targets Element
Cancelable Yes
Default action Varies
Context
(trusted events)

The click event type MUST be dispatched on the topmost event target indicated by the pointer, when the user presses down and releases the primary pointer button, or otherwise activates the pointer in a manner that simulates such an action. The actuation method of the mouse button depends upon the pointer device and the environment configuration, e.g., it MAY depend on the screen location or the delay between the press and release of the pointing device button.

Note: The click event should only be fired for the primary pointer button (i.e., when MouseEvent.button value is 0, MouseEvent.buttons value is 1). Secondary buttons (like the middle or right button on a standard mouse) MUST NOT fire click events.

The click event MAY be preceded by the mousedown and mouseup events on the same element, disregarding changes between other node types (e.g., text nodes). Depending upon the environment configuration, the click event MAY be dispatched if one or more of the event types mouseover, mousemove, and mouseout occur between the press and release of the pointing device button. The click event MAY also be followed by the dblclick event.

If a user mouses down on a text node child of a <p> element which has been styled with a large line-height, shifts the mouse slightly such that it is no longer over an area containing text but is still within the containing block of that <p> element (i.e., the pointer is between lines of the same text block, but not over the text node per se), then subsequently mouses up, this will likely still trigger a click event (if it falls within the normal temporal hysteresis for a click), since the user has stayed within the scope of the same element. Note that user-agent-generated mouse events are not dispatched on text nodes.

In addition to being associated with pointer devices, the click event type MUST be dispatched as part of an element activation, as described in Activation triggers and behavior.

Note: For maximum accessibility, content authors are encouraged to use the click event type when defining activation behavior for custom controls, rather than other pointing-device event types such as mousedown or mouseup, which are more device-specific. Though the click event type has its origins in pointer devices (e.g., a mouse), subsequent implementation enhancements have extended it beyond that association, and it can be considered a device-independent event type for element activation.

The default action of the click event type varies based on the event target of the event and the value of the MouseEvent.button or MouseEvent.buttons attributes. Typical default actions of the click event type are as follows:

dblclick
Type dblclick
Interface MouseEvent
Sync / Async Sync
Bubbles Yes
Trusted Targets Element
Cancelable Yes
Default action None
Context
(trusted events)

A user agent MUST dispatch this event when the primary button of a pointing device is clicked twice over an element. The definition of a double click depends on the environment configuration, except that the event target MUST be the same between mousedown, mouseup, and dblclick. This event type MUST be dispatched after the event type click if a click and double click occur simultaneously, and after the event type mouseup otherwise.

Note: As with the click event, the dblclick event should only be fired for the primary pointer button. Secondary buttons MUST NOT fire dblclick events.

Note: Canceling the click event does not affect the firing of a dblclick event.

As with the click event type, the default action of the dblclick event type varies based on the event target of the event and the value of the MouseEvent.button or MouseEvent.buttons attributes. Normally, the typical default actions of the dblclick event type match those of the click event type, with the following additional behavior:

  • If the event target is selectable, the default action MUST be to select part or all of the selectable content. Subsequent clicks MAY select additional selectable portions of that content.
mousedown
Type mousedown
Interface MouseEvent
Sync / Async Sync
Bubbles Yes
Trusted Targets Element
Cancelable Yes
Default action Varies: Start a drag/drop operation; start a text selection; start a scroll/pan interaction (in combination with the middle mouse button, if supported)
Context
(trusted events)

A user agent MUST dispatch this event when a pointing device button is pressed over an element.

Note: Many implementations use the mousedown event to begin a variety of contextually dependent default actions. These default actions can be prevented if this event is canceled. Some of these default actions could include: beginning a drag/drop interaction with an image or link, starting text selection, etc. Additionally, some implementations provide a mouse-driven panning feature that is activated when the middle mouse button is pressed at the time the mousedown event is dispatched.

mouseenter
Type mouseenter
Interface MouseEvent
Sync / Async Sync
Bubbles No
Trusted Targets Element
Cancelable No
Default action None
Context
(trusted events)

A user agent MUST dispatch this event when a pointing device is moved onto the boundaries of an element or one of its descendent elements. This event type is similar to mouseover, but differs in that it does not bubble, and MUST NOT be dispatched when the pointer device moves from an element onto the boundaries of one of its descendent elements.

Note: There are similarities between this event type and the CSS :hover pseudo-class [CSS2.1]. See also the mouseleave event type.

mouseleave
Type mouseleave
Interface MouseEvent
Sync / Async Sync
Bubbles No
Trusted Targets Element
Cancelable No
Default action None
Context
(trusted events)

A user agent MUST dispatch this event when a pointing device is moved off of the boundaries of an element and all of its descendent elements. This event type is similar to mouseout, but differs in that does not bubble, and that it MUST NOT be dispatched until the pointing device has left the boundaries of the element and the boundaries of all of its children.

Note: There are similarities between this event type and the CSS :hover pseudo-class [CSS2.1]. See also the mouseenter event type.

mousemove
Type mousemove
Interface MouseEvent
Sync / Async Sync
Bubbles Yes
Trusted Targets Element
Cancelable Yes
Default action None
Context
(trusted events)

A user agent MUST dispatch this event when a pointing device is moved while it is over an element. The frequency rate of events while the pointing device is moved is implementation-, device-, and platform-specific, but multiple consecutive mousemove events SHOULD be fired for sustained pointer-device movement, rather than a single event for each instance of mouse movement. Implementations are encouraged to determine the optimal frequency rate to balance responsiveness with performance.

Authoring Note: In some implementation environments, such as a browser, mousemove events can continue to fire if the user began a drag operation (e.g., a mouse button is pressed) and the pointing device has left the boundary of the user agent.

Note: This event was formerly specified to be non-cancelable in DOM Level 2 Events [DOM2 Events], but was changed to reflect existing interoperability between user agents.

mouseout
Type mouseout
Interface MouseEvent
Sync / Async Sync
Bubbles Yes
Trusted Targets Element
Cancelable Yes
Default action None
Context
(trusted events)

A user agent MUST dispatch this event when a pointing device is moved off of the boundaries of an element. This event type is similar to mouseleave, but differs in that does bubble, and that it MUST be dispatched when the pointer device moves from an element onto the boundaries of one of its descendent elements.

Note: See also the mouseover event type.

mouseover
Type mouseover
Interface MouseEvent
Sync / Async Sync
Bubbles Yes
Trusted Targets Element
Cancelable Yes
Default action None
Context
(trusted events)

A user agent MUST dispatch this event when a pointing device is moved onto the boundaries of an element. This event type is similar to mouseenter, but differs in that it bubbles, and that it MUST be dispatched when the pointer device moves onto the boundaries of an element whose ancestor element is the event target for the same event listener instance.

Note: See also the mouseout event type.

mouseup
Type mouseup
Interface MouseEvent
Sync / Async Sync
Bubbles Yes
Trusted Targets Element
Cancelable Yes
Default action Invoke a context menu (in combination with the right mouse button, if supported)
Context
(trusted events)

A user agent MUST dispatch this event when a pointing device button is released over an element.

Note: Many implementations will invoke a context menu as the default action of this event if the right mouse button is being released.

Authoring Note: In some implementation environments, such as a browser, a mouseup event can be dispatched even if the pointing device has left the boundary of the user agent, e.g., if the user began a drag operation with a mouse button pressed.

5.4 Wheel Event Types

Wheels are devices that can be rotated in one or more spatial dimensions, and which can be associated with a pointer device. The coordinate system depends on the environment configuration.

The user's environment might be configured to associate vertical scrolling with rotation along the y-axis, horizontal scrolling with rotation along the x-axis, and zooming with rotation along the z-axis.

The deltaX, deltaY, and deltaZ attributes of WheelEvent objects indicate a measurement along their respective axes in units of pixels, lines, or pages. The reported measurements are provided after an environment-specific algorithm translates the actual rotation/movement of the wheel device into the appropriate values and units.

Authoring Note: A user's environment settings can be customized to interpret actual rotation/movement of a wheel device in different ways. One movement of a common dented mouse wheel can produce a measurement of 162 pixels (162 is just an example value, actual values can depend on the current screen dimensions of the user-agent). But a user can change their default environment settings to speed-up their mouse wheel, increasing this number. Furthermore, some mouse wheel software can support acceleration (the faster the wheel is rotated/moved, the greater the delta of each measurement) or even sub-pixel rotation measurements. Because of this, authors can not assume a given rotation amount in one user agent will produce the same delta value in all user agents.

The sign (positive or negative) of the values of the deltaX, deltaY, and deltaZ attributes MUST be consistent between multiple dispatches of the wheel event while the motion of the actual wheel device is rotating/moving in the same direction. If a user agent scrolls as the default action of the wheel event then the sign of the delta SHOULD be given by a right-hand coordinate system where positive X, Y, and Z axes are directed towards the right-most edge, bottom-most edge, and farthest depth (away from the user) of the document, respectively.

Note: Individual user agents can (depending on their environment and hardware configuration) interpret the same physical user interaction on the wheel differently. For example, a vertical swipe on the edge of a trackpad from top to bottom can be interpreted as a wheel action intended to either scroll the page down or to pan the page up (i.e., resulting in either a positive or negative deltaY value respectively).

5.4.1 Interface WheelEvent

Introduced in DOM Level 3

The WheelEvent interface provides specific contextual information associated with wheel events.

To create an instance of the WheelEvent interface, use the DocumentEvent.createEvent("WheelEvent") method call. 

[Constructor(DOMString typeArg, optional WheelEventInit wheelEventInitDict)]
interface WheelEvent : MouseEvent {
    // DeltaModeCode
    const unsigned long DOM_DELTA_PIXEL = 0x00;
    const unsigned long DOM_DELTA_LINE = 0x01;
    const unsigned long DOM_DELTA_PAGE = 0x02;
    readonly    attribute double        deltaX;
    readonly    attribute double        deltaY;
    readonly    attribute double        deltaZ;
    readonly    attribute unsigned long deltaMode;
};
5.4.1.1 Attributes
deltaMode of type unsigned long, readonly

The deltaMode attribute contains an indication of the units of measurement for the delta values. The default value is DOM_DELTA_PIXEL (pixels).

This attribute MUST be set to one of the DOM_DELTA constants to indicate the units of measurement for the delta values. The precise measurement is specific to device, operating system, and application configurations.

The un-initialized value of this attribute MUST be 0.

deltaX of type double, readonly

In user agents where the default action of the wheel event is to scroll, the value MUST be the measurement along the x-axis (in pixels, lines, or pages) to be scrolled in the case where the event is not cancelled. Otherwise, this is an implementation-specific measurement (in pixels, lines, or pages) of the movement of a wheel device around the x-axis.

The un-initialized value of this attribute MUST be 0.0.

deltaY of type double, readonly

In user agents where the default action of the wheel event is to scroll, the value MUST be the measurement along the y-axis (in pixels, lines, or pages) to be scrolled in the case where the event is not cancelled. Otherwise, this is an implementation-specific measurement (in pixels, lines, or pages) of the movement of a wheel device around the y-axis.

The un-initialized value of this attribute MUST be 0.0.

deltaZ of type double, readonly

In user agents where the default action of the wheel event is to scroll, the value MUST be the measurement along the z-axis (in pixels, lines, or pages) to be scrolled in the case where the event is not cancelled. Otherwise, this is an implementation-specific measurement (in pixels, lines, or pages) of the movement of a wheel device around the z-axis.

The un-initialized value of this attribute MUST be 0.0.

5.4.1.2 Constants
DOM_DELTA_LINE of type unsigned long

The units of measurement for the delta MUST be individual lines of text. This is the case for many form controls.

DOM_DELTA_PAGE of type unsigned long

The units of measurement for the delta MUST be pages, either defined as a single screen or as a demarcated page.

DOM_DELTA_PIXEL of type unsigned long

The units of measurement for the delta MUST be pixels. This is the most typical case in most operating system and implementation configurations.

dictionary WheelEventInit : MouseEventInit {
    double        deltaX = 0.0;
    double        deltaY = 0.0;
    double        deltaZ = 0.0;
    unsigned long deltaMode = 0;
};
5.4.1.3 Dictionary WheelEventInit Members
deltaMode of type unsigned long, defaulting to 0

Initializes the deltaMode attribute on the WheelEvent object to the enumerated values 0, 1, or 2, which represent the amount of pixels scrolled (DOM_DELTA_PIXEL), lines scrolled (DOM_DELTA_LINE), or pages scrolled (DOM_DELTA_PAGE) if the rotation of the wheel would have resulted in scrolling.

deltaX of type double, defaulting to 0.0

See deltaZ attribute.

deltaY of type double, defaulting to 0.0

See deltaZ attribute.

deltaZ of type double, defaulting to 0.0

Initializes the deltaZ attribute of the WheelEvent object. Relative positive values for this attribute (as well as the deltaX and deltaY attributes) are given by a right-hand coordinate system where the X, Y, and Z axes are directed towards the right-most edge, bottom-most edge, and farthest depth (away from the user) of the document, respectively. Negative relative values are in the respective opposite directions.

The Wheel event types are listed below.

wheel
Type wheel
Interface WheelEvent
Sync / Async Async
Bubbles Yes
Trusted Targets Element
Cancelable Yes
Default action Scroll (or zoom) the document
Context
(trusted events)
  • Event.target: topmost event target
  • UIEvent.view: Window
  • UIEvent.detail: 0
  • MouseEvent.screenX: if the wheel is associated with a pointing device, the value based on the pointer position on the screen, otherwise 0
  • MouseEvent.screenY: if the wheel is associated with a pointing device, the value based on the pointer position on the screen, otherwise 0
  • MouseEvent.clientX: if the wheel is associated with a pointing device, the value based on the pointer position within the viewport, otherwise 0
  • MouseEvent.clientY : if the wheel is associated with a pointing device, the value based on the pointer position within the viewport, otherwise 0
  • MouseEvent.altKey: true if 'Alt' modifier was active, otherwise false
  • MouseEvent.ctrlKey: true if 'Control' modifier was active, otherwise false
  • MouseEvent.shiftKey: true if 'Shift' modifier was active, otherwise false
  • MouseEvent.metaKey: true if 'Meta' modifier was active, otherwise false
  • MouseEvent.button: if wheel is associated with a pointing device, value based on current button pressed, otherwise 0
  • MouseEvent.buttons: if wheel is associated with a pointing device, value based on all buttons current depressed, 0 if no buttons pressed
  • MouseEvent.relatedTarget: indicates the event target the pointing device is pointing at, if any.
  • WheelEvent.deltaX: expected amount that the page will scroll along the x-axis according to the deltaMode units; or an implemenation-specific value of movement of a wheel around the x-axis
  • WheelEvent.deltaY: expected amount that the page will scroll along the y-axis according to the deltaMode units; or an implemenation-specific value of movement of a wheel around the y-axis
  • WheelEvent.deltaZ: expected amount that the page will scroll along the z-axis according to the deltaMode units; or an implemenation-specific value of movement of a wheel around the z-axis
  • WheelEvent.deltaMode: unit indicator (pixels, lines, or pages) for the deltaX, deltaY, and deltaZ attributes

A user agent MUST dispatch this event when a mouse wheel has been rotated around any axis, or when an equivalent input device (such as a mouse-ball, certain tablets or touchpads, etc.) has emulated such an action. Depending on the platform and input device, diagonal wheel deltas MAY be delivered either as a single wheel event with multiple non-zero axes or as separate wheel events for each non-zero axis.

The typical default action of the wheel event type is to scroll (or in some cases, zoom) the document by the indicated amount. If this event is canceled, the implementation MUST NOT scroll or zoom the document (or perform whatever other implementation-specific default action is associated with this event type).

Note: In some user agents, or with some input devices, the speed that the wheel has been turned can affect the delta values, with a faster speed producing a higher delta value.

5.5 Input Event Types

Input events are sent as notifications whenever the DOM is being updated.

5.5.1 Interface InputEvent

Introduced in DOM Level 3

[Constructor(DOMString typeArg, optional InputEventInit inputEventInitDict)]
interface InputEvent : UIEvent {
    readonly    attribute DOMString data;
    readonly    attribute boolean   isComposing;
};
5.5.1.1 Attributes
data of type DOMString, readonly

data holds the value of the characters generated by an input method. This MAY be a single Unicode character or a non-empty sequence of Unicode characters [Unicode]. Characters SHOULD be normalized as defined by the Unicode normalization form NFC, defined in [UAX #15]. This attribute MAY contain the empty string.

The un-initialized value of this attribute MUST be "" (the empty string).

isComposing of type boolean, readonly

true if the input event occurs as part of a composition session, i.e., after a compositionstart event and before the corresponding compositionend event.

The un-initialized value of this attribute MUST be false.

dictionary InputEventInit : UIEventInit {
    DOMString data = "";
    boolean   isComposing = false;
};
5.5.1.2 Dictionary InputEventInit Members
data of type DOMString, defaulting to ""

Initializes the data attribute of the InputEvent object.

isComposing of type boolean, defaulting to false

Initializes the isComposing attribute of the InputEvent object.

5.5.2 Input Event Order

The input events defined in this specification MUST occur in a set order relative to one another.

1. beforeinput  
  DOM element is updated
2. input  

The Input event types are listed below.

beforeinput
Type beforeinput
Interface InputEvent
Sync / Async Sync
Bubbles Yes
Trusted Targets Element (specifically: control types such as HTMLInputElement, etc.) or any Element with contenteditable attribute enabled.
Cancelable Yes
Default action Update the DOM element
Context
(trusted events)

A user agent MUST dispatch this event when the DOM is about to be updated.

input
Type input
Interface InputEvent
Sync / Async Sync
Bubbles Yes
Trusted Targets Element (specifically: control types such as HTMLInputElement, etc.) or any Element with contenteditable attribute enabled.
Cancelable No
Default action None
Context
(trusted events)

A user agent MUST dispatch this event immediately after the DOM has been updated.

5.6 Keyboard Event Types

Keyboard events are device dependent, i.e., they rely on the capabilities of the input devices and how they are mapped in the operating systems. Refer to Keyboard events and key values for more details, including examples on how Keyboard Events are used in combination with Composition Events. Depending on the character generation device, keyboard events might not be generated.

Authoring Note: Keyboard events are only one modality of providing textual input. For editing scenarios, consider also using the InputEvent as an alternate to (or in addition to) keyboard events.

5.6.1 Interface KeyboardEvent

Introduced in DOM Level 3

The KeyboardEvent interface provides specific contextual information associated with keyboard devices. Each keyboard event references a key using a value. Keyboard events are commonly directed at the element that has the focus.

The KeyboardEvent interface provides convenient attributes for some common modifiers keys: KeyboardEvent.ctrlKey, KeyboardEvent.shiftKey, KeyboardEvent.altKey, KeyboardEvent.metaKey. These attributes are equivalent to using the method KeyboardEvent.getModifierState(keyArg) with 'Control', 'Shift', 'Alt', or 'Meta' respectively.

To create an instance of the KeyboardEvent interface, use the DocumentEvent.createEvent("KeyboardEvent") method call. 

[Constructor(DOMString typeArg, optional KeyboardEventInit keyboardEventInitDict)]
interface KeyboardEvent : UIEvent {
    // KeyLocationCode
    const unsigned long DOM_KEY_LOCATION_STANDARD = 0x00;
    const unsigned long DOM_KEY_LOCATION_LEFT = 0x01;
    const unsigned long DOM_KEY_LOCATION_RIGHT = 0x02;
    const unsigned long DOM_KEY_LOCATION_NUMPAD = 0x03;
    readonly    attribute DOMString     key;
    readonly    attribute DOMString     code;
    readonly    attribute unsigned long location;
    readonly    attribute boolean       ctrlKey;
    readonly    attribute boolean       shiftKey;
    readonly    attribute boolean       altKey;
    readonly    attribute boolean       metaKey;
    readonly    attribute boolean       repeat;
    readonly    attribute boolean       isComposing;
    boolean getModifierState (DOMString keyArg);
};
5.6.1.1 Attributes
altKey of type boolean, readonly

true if the 'Alt' (alternative) (or 'Option') key modifier was active.

The un-initialized value of this attribute MUST be false.

code of type DOMString, readonly

code holds a string that identifies the physical key being pressed. The value is not affected by the current keyboard layout or modifier state, so a particular key will always return the same value.

The un-initialized value of this attribute MUST be "" (the empty string).

ctrlKey of type boolean, readonly

true if the 'Control' (control) key modifier was active.

The un-initialized value of this attribute MUST be false.

isComposing of type boolean, readonly

true if the key event occurs as part of a composition session, i.e., after a compositionstart event and before the corresponding compositionend event.

The un-initialized value of this attribute MUST be false.

key of type DOMString, readonly

key holds the key value of the key pressed. If the value is has a printed representation, it MUST be a non-empty Unicode character string, conforming to the algorithm for determining the key value defined in this specification. If the value is a control key which has no printed representation, it MUST be one of the key values defined in the key values set, as determined by the algorithm for determining the key value. Implementations that are unable to identify a key MUST use the key value 'Unidentified'.

Note: The key attribute is not related to the legacy keyCode attribute and does not have the same set of values.

The un-initialized value of this attribute MUST be "" (the empty string).

location of type unsigned long, readonly

The location attribute contains an indication of the location of the key on the device.

This attribute MUST be set to one of the DOM_KEY_LOCATION constants to indicate the location of a key on the device. In case a DOM implementation wishes to provide a new location value, a value different from the defined constant values MUST be used.

The un-initialized value of this attribute MUST be 0.

metaKey of type boolean, readonly

true if the meta ('Meta') key modifier was active.

Note: The 'Command' ('⌘') key modifier on Macintosh systems is represented using this key modifier.

The un-initialized value of this attribute MUST be false.

repeat of type boolean, readonly

true if the key has been pressed in a sustained manner. Holding down a key MUST result in the repeating the events keydown, beforeinput, input in this order, at a rate determined by the system configuration. For mobile devices which have long-key-press behavior, the first key event with a repeat attribute value of 'true' MUST serve as an indication of a long-key-press. The length of time that the key MUST be pressed in order to begin repeating is configuration-dependent.

The un-initialized value of this attribute MUST be false.

shiftKey of type boolean, readonly

true if the shift ('Shift') key modifier was active.

The un-initialized value of this attribute MUST be false.

5.6.1.2 Methods
getModifierState

Queries the state of a modifier using a key value. See Modifier keys for a list of valid (case-sensitive) arguments to this method.

ParameterTypeNullableOptionalDescription
keyArg DOMString ✘ ✘

A modifier key value. Valid modifier keys are defined in the Modifier Keys table in [DOM3 key Values].

Returns true if it is a modifier key and the modifier is activated, false otherwise.

Note: If an application wishes to distinguish between right and left modifiers, this information could be deduced using keyboard events and KeyboardEvent.location.
Return type: boolean
5.6.1.3 Constants
DOM_KEY_LOCATION_LEFT of type unsigned long

The key activated originated from the left key location (when there is more than one possible location for this key).

The left 'Control' key on a PC 101 Key US keyboard.

DOM_KEY_LOCATION_NUMPAD of type unsigned long

The key activation originated on the numeric keypad or with a virtual key corresponding to the numeric keypad (when there is more than one possible location for this key). Note that the 'NumLock' key should always be encoded with a location of DOM_KEY_LOCATION_STANDARD.

The '1' key on a PC 101 Key US keyboard located on the numeric pad.

DOM_KEY_LOCATION_RIGHT of type unsigned long

The key activation originated from the right key location (when there is more than one possible location for this key).

The right 'Shift' key on a PC 101 Key US keyboard.

DOM_KEY_LOCATION_STANDARD of type unsigned long

The key activation MUST NOT be distinguished as the left or right version of the key, and (other than the 'NumLock' key) did not originate from the numeric keypad (or did not originate with a virtual key corresponding to the numeric keypad).

The 'Q' key on a PC 101 Key US keyboard.

The 'NumLock' key on a PC 101 Key US keyboard.

The '1' key on a PC 101 Key US keyboard located in the main section of the keyboard.

dictionary KeyboardEventInit : SharedKeyboardAndMouseEventInit {
    DOMString     key = "";
    DOMString     code = "";
    unsigned long location = 0;
    boolean       repeat = false;
    boolean       isComposing = false;
};
5.6.1.4 Dictionary KeyboardEventInit Members
code of type DOMString, defaulting to ""

Initializes the code attribute of the KeyboardEvent object to the unicode character string representing the key that was pressed, ignoring any keyboard modifications such as keyboard layout. This value should be one of the code values defined in [DOM3 code Values].

isComposing of type boolean, defaulting to false

Initializes the isComposing attribute of the KeyboardEvent object. This attribute should be set to true if the event being constructed occurs as part of a composition sequence, false otherwise.

key of type DOMString, defaulting to ""

Initializes the key attribute of the KeyboardEvent object to the unicode character string representing the meaning of a key after taking into account all keyboard modifications (such as shift-state). This value is the final effective value of the key. If the key is not a printable character, then it should be one of the key values defined in [DOM3 key Values].

location of type unsigned long, defaulting to 0

Initializes the location attribute of the KeyboardEvent object to one of the following location numerical constants:

  • KeyboardEvent.DOM_KEY_LOCATION_STANDARD (numerical value 0)
  • KeyboardEvent.DOM_KEY_LOCATION_LEFT (numerical value 1)
  • KeyboardEvent.DOM_KEY_LOCATION_RIGHT (numerical value 2)
  • KeyboardEvent.DOM_KEY_LOCATION_NUMPAD (numerical value 3)
repeat of type boolean, defaulting to false

Initializes the repeat attribute of the KeyboardEvent object. This attribute should be set to true if the the current KeyboardEvent is considered part of a repeating sequence of similar events caused by the long depression of any single key, false otherwise.

Warning!

Legacy keyboard event implementations include three additional attributes, keyCode, charCode, and which. The keyCode attribute indicates a numeric value associated with a particular key on a computer keyboard, while the charCode attribute indicates the ASCII value of the character associated with that key (which might be the same as the keyCode value) and is applicable only to keys that produce a character value.

In practice, keyCode and charCode are inconsistent across platforms and even the same implementation on different operating systems or using different localizations. DOM Level 3 Events does not define values for either keyCode or charCode, or behavior for charCode. In conforming DOM Level 3 Events implementations, content authors can instead use KeyboardEvent.key and KeyboardEvent.code.

For more information, see the informative appendix on Legacy key attributes.

Note: For compatibility with existing content, virtual keyboards, such as software keyboards on screen-based input devices, are expected to produce the normal range of keyboard events, even though they do not possess physical keys.

Note: In some implementations or system configurations, some key events, or their values, might be suppressed by the IME in use.

5.6.2 Keyboard Event Order

The keyboard events defined in this specification occur in a set order relative to one another, for any given key:

  Event NameNotes
1. keydown  
2. beforeinput (only for keys which produce a character value)
    Any default actions related to this key, such as inserting a character in to the DOM.
3. input (only for keys which have updated the DOM)
    Any events as a result of the key being held for a sustained period (see below).
4. keyup  

If the key is depressed for a sustained period, the following events MAY repeat at an environment-dependent rate:

  Event NameNotes
1. keydown (with repeat attribute set to true)
2. beforeinput (only for keys which produce a character value)
    Any default actions related to this key, such as inserting a character in to the DOM.
3. input (only for keys which have updated the DOM)

Note: Typically, any default actions associated with any particular key are completed before the keyup event is dispatched. This might delay the keyup event slightly (though this is not likely to be a perceptible delay).

The event target of a key event is the currently focused element which is processing the keyboard activity. This is often an HTML input element or a textual element which is editable, but MAY be an element defined by the host language to accept keyboard input for non-text purposes, such as the activation of an accelerator key or trigger of some other behavior. If no suitable element is in focus, the event target will be the HTML body element if available, otherwise the root element.

Note: The event target might change between different key events. For example, a keydown event for the 'Tab' key will likely have a different event target than the keyup event on the same keystroke.

The keyboard event types are listed below.

keydown
Type keydown
Interface KeyboardEvent
Sync / Async Sync
Bubbles Yes
Trusted Targets Element
Cancelable Yes
Default action Varies: beforeinput and input events; launch text composition system; blur and focus events; keypress event; activation behavior; other event
Context
(trusted events)

A user agent MUST dispatch this event when a key is pressed down. The keydown event type is device dependent and relies on the capabilities of the input devices and how they are mapped in the operating system. This event type MUST be generated after the key mapping. This event type MUST be dispatched before the beforeinput, input, and keyup events associated with the same key.

The default action of the keydown event depends upon the key:

  • If the key is associated with a character, the default action MUST be to dispatch a beforeinput event followed by an input event. In the case where the key which is associated with multiple characters (such as with a macro or certain sequences of dead keys), the default action MUST be to dispatch one set of beforeinput / input events for each character
  • If the key is associated with a text composition system, the default action MUST be to launch that system
  • If the key is the 'Tab' key, the default action MUST be to shift the document focus from the currently focused element (if any) to the new focused element, as described in Focus Event Types
  • If the key is the 'Enter' or ' ' key and the current focus is on a state-changing element, the default action MUST be to dispatch a click event, and a DOMActivate event if that event type is supported by the user agent (refer to activation triggers and behavior for more details)

If this event is canceled, the associated event types MUST NOT be dispatched, and the associated actions MUST NOT be performed.

Note: The keydown and keyup events are traditionally associated with detecting any key, not just those which produce a character value.

keyup
Type keyup
Interface KeyboardEvent
Sync / Async Sync
Bubbles Yes
Trusted Targets Element
Cancelable Yes
Default action None
Context
(trusted events)

A user agent MUST dispatch this event when a key is released. The keyup event type is device dependent and relies on the capabilities of the input devices and how they are mapped in the operating system. This event type MUST be generated after the key mapping. This event type MUST be dispatched after the keydown, beforeinput, and input events associated with the same key.

Note: the keydown and keyup events are traditionally associated with detecting any key, not just those which produce a character value.

5.7 Composition Event Types

Composition Events provide a means for inputing text in a supplementary or alternate manner than by Keyboard Events, in order to allow the use of characters that might not be commonly available on keyboard. For example, Composition Events might be used to add accents to characters despite their absence from standard US keyboards, to build up logograms of many Asian languages from their base components or categories, to select word choices from a combination of key presses on a mobile device keyboard, or to convert voice commands into text using a speech recognition processor. Refer to Keyboard events and key values for examples on how Composition Events are used in combination with keyboard events.

Conceptually, a composition session consists of one compositionstart event, one or more compositionupdate events, and one compositionend event, with the value of the data attribute persisting between each stage of this event chain during each session.

Note: While a composition session is active, keyboard events can be dispatched to the DOM if the keyboard is the input device used with the composition session. See the compositionstart event details and IME section for relevent event ordering.

Not all IME systems or devices expose the necessary data to the DOM, so the active composition string (the Reading Window or candidate selection menu option) might not be available through this interface, in which case the selection MAY be represented by the empty string.

5.7.1 Interface CompositionEvent

Introduced in DOM Level 3

The CompositionEvent interface provides specific contextual information associated with Composition Events.

To create an instance of the CompositionEvent interface, use the DocumentEvent.createEvent("CompositionEvent") method call.

[Constructor(DOMString typeArg, optional CompositionEventInit compositionEventInitDict)]
interface CompositionEvent : UIEvent {
    readonly    attribute DOMString data;
};
5.7.1.1 Attributes
data of type DOMString, readonly

data holds the value of the characters generated by an input method. This MAY be a single Unicode character or a non-empty sequence of Unicode characters [Unicode]. Characters SHOULD be normalized as defined by the Unicode normalization form NFC, defined in [UAX #15]. This attribute MAY be the empty string.

The un-initialized value of this attribute MUST be "" (the empty string).

dictionary CompositionEventInit : UIEventInit {
    DOMString data = "";
};
5.7.1.2 Dictionary CompositionEventInit Members
data of type DOMString, defaulting to ""

Initializes the data attribute of the CompositionEvent object to the characters generated by the IME composition.

5.7.2 Composition Event Order

The Composition Events defined in this specification MUST occur in the following set order relative to one another:

  Event NameNotes
1. compositionstart  
2. compositionupdate Multiple events
3. compositionend  

5.7.3 Handwriting Recognition Systems

The following example describes a possible sequence of events when composing a text passage text with a handwriting recognition system, such as on a pen tablet, as modeled using Composition Events.

  Event NameCompositionEvent
data		Notes
1. compositionstart ''  
      User writes word on tablet surface
2. compositionupdate 'test'  
      User rejects first word-match suggestion, selects different match
3. compositionupdate 'text'  
4. compositionend 'text'  

5.7.4 Canceling Composition Events

If a keydown event is canceled then any Composition Events that would have fired as a result of that keydown SHOULD not be dispatched:

  Event NameNotes
1. keydown The default action is prevented, e.g., by invoking Event.preventDefault().
    No Composition Events are dispatched
2. keyup  

If the initial compositionstart event is canceled then the text composition session SHOULD be terminated. Regardless of whether or not the composition session is terminated, the compositionend event MUST be sent.

  Event NameNotes
1. keydown  
2. compositionstart The default action is prevented, e.g., by invoking Event.preventDefault().
    No Composition Events are dispatched
3. compositionend  
4. keyup  

5.7.5 Key Events During Composition

During the composition session, all keydown and keyup events MAY be suppressed.

5.7.5.1 Including Key Events During Composition

If a user agent does not suppress these events during composition, then it MUST set the key event's isComposing attribute to true for any events that occur during a composition session.

  Event NameKeyboardEvent
isComposing		Notes
1. keydown false This is the key event that initiates the composition.
2. compositionstart    
3. compositionupdate    
4. keyup true  
  ...   Any key events sent during the composition session MUST have isComposing set to true.
5. keydown true This is the key event that exits the composition.
6. compositionend    
7. keyup false  
5.7.5.2 Suppressing Key Events During Composition

If key events are suppressed between compositionstart and compositionend, then the first or last key pressed might result in unmatched keydown and keyup events. If a user agent suppresses key events during composition, then it MUST ensure that all keydown and keyup events occur in matching pairs.

To ensure that the initial keydown has a matching keyup, a user agent might insert an extra keyup to match the keydown that initiated a composition session, as shown in the following example:

  Event NameKeyboardEvent
isComposing		Notes
1. keydown false This is the key event that initiates the composition.
2. compositionstart    
3. compositionupdate    
4. keyup true This event would normally be suppressed because of the ongoing composition session, but it is sent to match the previously sent keydown event.
  ...   Any other key events that occur during the composition session are suppressed.
5. compositionend    

To ensure that the composition session doesn't end with a dangling keyup event, a user agent can choose either (A) to suppress this keyup event, or (B) to insert an extra keydown event.

An example event sequence where both the keydown and keyup events have been suppressed:

  Event NameKeyboardEvent
isComposing		Notes
      keydown for key that exits IME suppressed during composition session
1. compositionend    
      A keyup event would normally be sent at this time, but it is suppressed to avoid generating an unmatched keyup event.

An example event sequence where a keydown has been inserted:

  Event NameKeyboardEvent
isComposing		Notes
      keydown for key that exits IME suppressed during composition session
1. compositionend    
2. keydown false This is key event that was suppressed earlier. It is sent now to match the upcoming keyup.
3. keyup false  

5.7.6 Input Events During Composition

During the composition session, the compositionupdate MUST be dispatched before the beforeinput and input events are sent.

  Event NameNotes
1. compositionupdate  
2. beforeinput  
    Any DOM updates occur at this point.
3. input  

Note: Most IMEs do not support canceling updates during a composition session.

When a composition session is finished, any beforeinput and input events MUST be dispatched after the compositionend event.

  Event NameNotes
1. compositionend  
2. beforeinput Sent only if we’re about to update the DOM (i.e., the composition was not canceled). Canceling this will prevent the DOM update and the input event.
    Any DOM updates occur at this point.
3. input Sent only if the DOM was updated.

Note: Some IMEs update the DOM before the compositionend event is dispatched. In this case, canceling the beforeinput event will have no effect (i.e., the input event will still fire).

5.7.7 Composition Event Types

The composition event types are listed below.

compositionstart
Type compositionstart
Interface CompositionEvent
Sync / Async Sync
Bubbles Yes
Trusted Targets Element
Cancelable Yes
Default action Start a new composition session when a text composition system is enabled
Context
(trusted events)

A user agent MUST dispatch this event when a text composition system is enabled and a new composition session is about to begin (or has begun, depending on the text composition system) in preparation for composing a passage of text. This event type is device-dependent, and MAY rely upon the capabilities of the text conversion system and how it is mapped into the operating system. When a keyboard is used to feed an input method editor, this event type is generated after a keydown event, but speech or handwriting recognition systems MAY send this event type without keyboard events. Some implementations MAY populate the data attribute of the compositionstart event with the text currently selected in the document (for editing and replacement). Otherwise, the value of the data attribute MUST be the empty string.

This event MUST be dispatched immediately before a text composition system begins a new composition session, and before the DOM is modified due to the composition process. The default action of this event is for the text composition system to start a new composition session. If this event is canceled, the text composition system SHOULD discard the current composition session.

Note: Canceling the compositionstart event type is distinct from canceling the text composition system itself (e.g., by hitting a cancel button or closing an IME window).

Note: Some IMEs do not support cancelling an in-progress composition session (e.g., such as GTK which doesn't presently have such an API). In these cases, calling preventDefault will not stop this event's default action.

compositionupdate
Type compositionupdate
Interface CompositionEvent
Sync / Async Sync
Bubbles Yes
Trusted Targets Element
Cancelable No
Default action None
Context
(trusted events)

A user agent SHOULD dispatch this event during a composition session when a text composition system updates its active text passage with a new character, which is reflected in the string in CompositionEvent.data.

In text composition systems which keep the ongoing composition in sync with the input control, the compositionupdate event MUST be dispatched before the control is updated.

Some text composition systems might not expose this information to the DOM, in which case this event will not fire during the composition process.

If the composition session is canceled, this event will be fired immediately before the compositionend event, and the CompositionEvent.data attribute will be set to the empty string.

compositionend
Type compositionend
Interface CompositionEvent
Sync / Async Sync
Bubbles Yes
Trusted Targets Element
Cancelable No
Default action None
Context
(trusted events)

A user agent MUST dispatch this event when a text composition system completes or cancels the current composition session, and the compositionend event MUST be dispatched after the control is updated.

This event is dispatched immediately after the text composition system completes the composition session (e.g., the IME is closed, minimized, switched out of focus, or otherwise dismissed, and the focus switched back to the user agent).

6. Keyboard events and key values

This section contains necessary information regarding keyboard events:

  • Explanation of keyboard layout, mapping, and key values.
  • Relations between keys, such as dead keys or modifiers keys.
  • Relations between keyboard events and their default actions.
  • The set of key values, and guidelines on how to extend this set.

Note: This section uses Serbian and Kanji characters which could be misrepresented or unavailable in the PDF version or printed version of this specification.

6.1 Keyboard Input

This section is informative

The relationship of each key to the complete keyboard has three separate aspects, each of which vary among different models and configurations of keyboards, particularly for locale-specific reasons:

  • Mechanical layout: the dimensions, size, and placement of the physical keys on the keyboard
  • Visual markings: the labels (or legends) that mark each key
  • Functional mapping: the abstract key-value association of each key.

This specification only defines the functional mapping, in terms of key values and code values, but briefly describes key legends for background.

6.1.1 Key Legends

This section is informative

The key legend is the visual marking that is printed or embossed on the key cap (the rectangular 'cap' that covers the mechanical switch for the key). These markings normally consist of one or more characters that a keystroke on that key will produce (such as 'F', '8', or 'ш'), or names or symbols which indicate that key's function (such as an upward-pointing arrow ⇧ indicating 'Shift', or the string 'Enter'). Keys are often referred to by this marking (e.g., Press the 'Shift' and 'F' keys.). Note, however, that the visual appearance of the key has no bearing on its digital representation, and in many configurations may be completely inaccurate. Even the control and function keys, such as 'Enter', MAY be mapped to different functionality, or even mapped as character keys.

For historical reasons, the character keys are typically marked with the capital-letter equivalents of the character value they produce, e.g., the 'F' key (the key marked with the glyph 'F'), will produce the character value 'f' when pressed without an active modifier key ('Shift') or modifier state ('CapsLock').

Note: Many keyboards contain keys that do not normally produce any characters, even though the symbol might have a Unicode equivalent. For example, the 'Shift' key might bear the symbol ⇧, which has the Unicode code point '\u21E7', but pressing the 'Shift' key will not produce this character value, and there is no Unicode code point for 'Shift'.

6.2 Key codes

A key code is an attribute of a keyboard event that can be used to identify the physical key associated with the keyboard event. It is similar to USB Usage IDs in that it provides a low-level value (similar to a scancode) that is vendor-neutral.

The primary purpose of the code attribute is to provide a consistent and coherent way to identify keys based on their physical location. In addition, it also provides a stable name (unaffected by the current keyboard state) that uniquely identifies each key on the keyboard.

The list of valid code values is defined in the DOM Level 3 KeyboardEvent code Values Specification [DOM3 code Values].

6.2.1 Motivation for Adding the code Attribute

The standard PC keyboard has a set of keys (which we refer to as writing system keys) that generate different key values based on the current keyboard layout selected by the user. This situation makes it difficult to write code that detects keys based on their physical location since the code would need to know which layout is in effect in order to know which key values to check for. A real-world example of this is a game that wants to use the 'W', 'A', 'S' and 'D' keys to control player movement. The code attribute solves this problem by providing a stable value to check that is not affected by the current keyboard layout.

In addition, the values in the key attribute depend as well on the current keyboard state. Because of this, the order in which keys are pressed and released in relation to modifier keys can affect the values stored in the key attribute. The code attribute solves this problem by providing a stable value that is not affected by the current keyboard state.

6.2.2 The Relationship Between key and code

key
The key attribute is intended for users who are interested in the meaning of the key being pressed, taking into account the current keyboard layout (and IME; dead keys are given a unique key value). Example use case: Detecting modified keys or bare modifier keys (e.g., to perform an action in response to a keyboard shortcut).
code
The code attribute is intended for users who are interested in the key that was pressed by the user, without any layout modifications applied. Example use case: Detecting WASD keys (e.g., for movement controls in a game) or trapping all keys (e.g., in a remote desktop client to send all keys to the remote host).

6.2.3 code Examples

Handling the Left and Right Alt Keys

Keyboard LayoutKeyboardEvent
key		KeyboardEvent
code		Notes
US 'Alt' 'AltLeft' DOM_KEY_LOCATION_LEFT
French 'Alt' 'AltLeft' DOM_KEY_LOCATION_LEFT
US 'Alt' 'AltRight' DOM_KEY_LOCATION_RIGHT
French 'AltGr' 'AltRight' DOM_KEY_LOCATION_RIGHT

In this example, checking the key attribute permits matching 'Alt' without worrying about which Alt key (left or right) was pressed. Checking the code attribute permits matching the right Alt key ('AltRight') without worrying about which layout is currently in effect.

Note that, in the French example, the 'Alt' and 'AltGr' keys retain their left and right location, even through there is only one of each key.

Handling the Single Quote Key

Keyboard LayoutKeyboardEvent
key		KeyboardEvent
code		Notes
US ''' 'Quote'  
Japanese ':' 'Quote'  
US Intl 'Dead' 'Quote'  

This example shows how dead key values are encoded in the attributes. The key values vary based on the current locale, whereas the code attribute returns a consistent value.

Handling the '2' Key (with and without Shift pressed)

Keyboard LayoutKeyboardEvent
key		KeyboardEvent
code		Notes
US '2' 'Digit2'  
US '@' 'Digit2' shiftKey
UK '2' 'Digit2'  
UK '"' 'Digit2' shiftKey
French 'é' 'Digit2'  
French '2' 'Digit2' shiftKey

Regardless of the current locale or the modifier key state, pressing the key labelled '2' on a US keyboard always results in 'Digit2' in the code attribute.

Sequence of Keyboard Events : 'Shift' and '2'

Compare the attribute values in the following two key event sequences. They both produce the '@' character on a US keyboard, but differ in the order in which the keys are released. In the first sequence, the order is: 'Shift' (down), '2' (down), '2' (up), 'Shift' (up).

  Event NameKeyboard LayoutKeyboardEvent
key		KeyboardEvent
code		Notes
1. keydown US 'Shift' 'ShiftLeft' DOM_KEY_LOCATION_LEFT
2. keydown US '@' 'Digit2' shiftKey
3. keypress US '@' ''  
4. keyup US '@' 'Digit2' shiftKey
5. keyup US 'Shift' 'ShiftLeft' DOM_KEY_LOCATION_LEFT

In the second sequence, the Shift is released before the 2, resulting in the following event order: 'Shift' (down), '2' (down), 'Shift' (up), '2' (up).

  Event NameKeyboard LayoutKeyboardEvent
key		KeyboardEvent
code		Notes
1. keydown US 'Shift' 'ShiftLeft' DOM_KEY_LOCATION_LEFT
2. keydown US '@' 'Digit2' shiftKey
3. keypress US '@' ''  
4. keyup US 'Shift' 'ShiftLeft' DOM_KEY_LOCATION_LEFT
5. keyup US '2' 'Digit2'  

Note that the values contained in the key attribute does not match between the keydown and keyup events for the '2' key. The code attribute provides a consistent value that is not affected by the current modifier state.

6.2.4 code and Virtual Keyboards

The usefulness of the code attribute is less obvious for virtual keyboards (and also for remote controls and chording keyboards). In general, if a virtual (or remote control) keyboard is mimicking the layout and functionality of a standard keyboard, then it MUST also set the code attribute as appropriate. For keyboards which are not mimicking the layout of a standard keyboard, then the code attribute MAY be set to the closest match on a standard keyboard or it MAY be left undefined.

For virtual keyboards with keys that produce different values based on some modifier state, the code value should be the key value generated when the button is pressed while the device is in its factory-reset state.

6.3 Keyboard Event key Values

A key value is a DOMString that can be used to indicate any given key on a keyboard, regardless of position or state, by the value it produces. These key values MAY be used as return values for keyboard events generated by the implementation, or as input values by the content author to specify desired input (such as for keyboard shortcuts).

The list of valid key values is defined in the DOM Level 3 KeyboardEvent key Values Specification [DOM3 key Values].

Key values can be used to detect the value of a key which has been pressed, using the KeyboardEvent.key attribute. Content authors can retrieve the character value of upper- or lower-case letters, number, symbols, or other character-producing keys, and also the key value of control keys, modifier keys, function keys, or other keys that do not generate characters. These values can be used for monitoring particular input strings, for detecting and acting on modifier key input in combination with other inputs (such as a mouse), for creating virtual keyboards, or for any number of other purposes.

Key values can also be used by content authors in string comparisons, as values for markup attributes (such as the HTML accesskey) in conforming host languages, or for other related purposes. A conforming host language SHOULD allow content authors to use either of the two equivalent string values for a key value: the character value, or the key value.

Note: While implementations will use the most relevant value for a key independently of the platform or keyboard layout mappings, content authors can not make assumptions on the ability of keyboard devices to generate them. When using keyboard events and key values for shortcut-key combinations, content authors can consider using numbers and function keys (F4, F5, and so on) instead of letters ([DWW95]) given that most keyboard layouts will provide keys for those.

A key value does not indicate a specific key on the physical keyboard, nor does it reflect the character printed on the key. A key value indicates the current value of the event with consideration to the current state of all active keys and key input modes (including shift modes), as reflected in the operating-system mapping of the keyboard and reported to the implementation. In other words, the key value for the key marked 'O' on a QWERTY keyboard has the key value 'o' in an unshifted state and 'O' in a shifted state. Because a user can map their keyboard to an arbitrary custom configuration, the content author is encouraged not to assume that a relationship exists between the shifted and unshifted states of a key and the majuscule form (uppercase or capital letters) and minuscule form (lowercase or small letters) of a character representation, but is encouraged instead to use the value of the KeyboardEvent.key attribute. For example, the Standard "102" Keyboard layout depicted in [DOM3 code Values] illustrates one possible set of key mappings on one possible keyboard layout. Many others exist, both standard and idiosyncratic.

Note: To simplify dead key support, when the operating-system mapping of the keyboard is handling a dead key state, the current state of the dead key sequence is not reported via the KeyboardEvent.key attribute. Rather, a key value of 'Dead' is reported. Instead, implementations generate composition events which contain the intermediate state of the dead key sequence reported via the CompositionEvent.data attribute. As in the previous example, the key value for the key marked 'O' on a QWERTY keyboard has a CompositionEvent.data value of 'ö' in an unshifted state during a dead-key operation to add an umlaut diacritic, and 'Ö' in a shifted state during a dead-key operation to add an umlaut diacritic.

It is also important to note that there is not a one-to-one relationship between key event states and key values. A particular key value might be associated with multiple keys. For example, many standard keyboards contain more than one key with the 'Shift' key value (normally distinguished by the KeyboardEvent.location values DOM_KEY_LOCATION_LEFT and DOM_KEY_LOCATION_RIGHT) or '8' key value (normally distinguished by the KeyboardEvent.location values DOM_KEY_LOCATION_STANDARD and DOM_KEY_LOCATION_NUMPAD), and user-configured custom keyboard layouts MAY duplicate any key value in multiple key-state scenarios (note that KeyboardEvent.location is intended for standard keyboard layouts, and cannot always indicate a meaningful distinction).

Finally, the meaning of any given character representation is context-dependent and complex. For example, in some contexts, the asterisk (star) glyph ('*') represents a footnote or emphasis (when bracketing a passage of text). However, in some documents or executable programs it is equivalent to the mathematical multiplication operation, while in other documents or executable programs, that function is reserved for the multiplication symbol ('×', Unicode value '\u00D7') or the Latin small letter 'x' (due to the lack of a multiplication key on many keyboards and the superficial resemblance of the glyphs '×' and 'x'). Thus, the semantic meaning or function of character representations is outside the scope of this specification.

6.3.1 Key Values and Unicode

The character values described in this specification are Unicode [Unicode] codepoints, and as such, have certain advantages.

The most obvious advantage is that it allows the content author to use the full range of internationalized language functionality available in the implementation, regardless of the limitations of the text input devices on the system. This opens up possibilities for virtual keyboards and Web-application-based input method editors.

Another benefit is that it allows the content author to utilize the Unicode general category properties programmatically.

With legacy keyboard event attributes such as keyCode and charCode, content authors are forced to filter key input using cryptic, platform- and implementation-specific numeric codes, with poor internationalization, such as the following pseudocode:

if ( ( event.charCode == 45 || event.charCode == 36 ) ||
     ( event.charCode >= 48 && event.charCode <= 57 ) ||
     ( event.charCode >= 96 && event.charCode <= 105 ) ) {
   // minus sign, dollar sign, and numeric characters from keyboard and numpad
   // ...
}
else if ( ( event.charCode >= 65 && event.charCode <= 90 ) ||
          ( event.charCode >= 97 && event.charCode <= 122 ) ) {
   // alphabetic characters from Latin character set, A-Z, a-z
   // ...
}
else {
   // ...
}

With key values and regular expressions, however, content authors can support selective and intuitive ranges for key-based input, in a cross-platform manner with advanced internationalization support, such as the following pseudocode:

if ( event.key == "-" || event.key.match("\p{Sc}") || event.key.match("\p{N}") ) {
   // minus sign, any currency symbol, and numeric characters (regardless of key location)
   // ...
}
else if ( event.key.match("\p{L}") ) {
   // alphabetic characters from any language, upper and lower case
   // ...
}
else {
   // ...
}

In addition, because Unicode categorizes each assigned code point into a group of code points used by a particular human writing system, even more advanced capabilities are possible.

A content author can match characters from a particular human script (e.g., Tibetan) using a regular expression such as \p{Tibetan}, to filter out other characters, or discover if a code point is in a certain code block (range of code points), using a regular expression like \p{InCyrillic}.

To facilitate this, implementations SHOULD support Unicode range detection using regular expressions, in a manner such as the Perl Compatible Regular Expressions (PCRE) [PCRE].

6.3.2 Modifier keys

Keyboard input uses modifier keys to change the normal behavior of a key. Like other keys, modifier keys generate keydown and keyup events, as shown in the example below. Some modifiers are activated while the key is being pressed down or maintained pressed such as 'Alt', 'Control', 'Shift', 'AltGraph', or 'Meta'. Others modifiers are activated depending on their state such as 'CapsLock', 'NumLock', or 'ScrollLock'. Change in the state happens when the modifier key is being pressed down. The KeyboardEvent interface provides convenient attributes for some common modifiers keys: KeyboardEvent.ctrlKey, KeyboardEvent.shiftKey, KeyboardEvent.altKey, KeyboardEvent.metaKey. Some operating systems simulate the 'AltGraph' modifier key with the combination of the 'Alt' and 'Control' modifier keys. Implementations are encouraged to use the 'AltGraph' modifier key.

The following example describes a possible sequence of events associated with the generation of the Unicode character Q (Latin Capital Letter Q, Unicode code point '\u0051') on a US keyboard using a US mapping:

  Event NameKeyboardEvent
key		ModifiersNotes
1. keydown 'Shift' shiftKey  
2. keydown 'Q' shiftKey Latin Capital Letter Q
3. beforeinput 'Q'    
4. input      
5. keyup 'Q' shiftKey  
6. keyup 'Shift'    

The following example describes an alternate sequence of keys to the example above, where the 'Shift' key is released before the 'Q' key. The key value for the key labeled 'Q' will revert to its unshifted value for the keyup event:

  Event NameKeyboardEvent
key		ModifiersNotes
1. keydown 'Shift' shiftKey  
2. keydown 'Q' shiftKey Latin Capital Letter Q
3. beforeinput 'Q'    
4. input      
5. keyup 'Shift'    
6. keyup 'q'   Latin Small Letter Q

The following example describes a possible sequence of keys that does not generate a Unicode character (using the same configuration):

  Event NameKeyboardEvent
key		ModifiersNotes
1. keydown 'Control' ctrlKey  
2. keydown 'v' ctrlKey Latin Small Letter V
  No beforeinput or input events are generated.
3. keyup 'v' ctrlKey Latin Small Letter V
4. keyup 'Control'    

The following example shows the sequence of events when both 'Shift' and 'Control' are pressed:

  Event NameKeyboardEvent
key		ModifiersNotes
1. keydown 'Control' ctrlKey  
2. keydown 'Shift' ctrlKey shiftKey  
3. keydown 'V' ctrlKey shiftKey Latin Capital Letter V
  No beforeinput or input events are generated.
4. keyup 'V' ctrlKey shiftKey Latin Capital Letter V
5. keyup 'Shift' ctrlKey  
6. keyup 'Control'    

For non-US keyboard layouts, the sequence of events is the same, but the value of the key is based on the current keyboard layout. The following example shows a sequence of events when an Arabic keyboard layout is used:

  Event NameKeyboardEvent
key		ModifiersNotes
1. keydown 'Control' ctrlKey  
2. keydown 'ر' ctrlKey Arabic Letter Reh
  No beforeinput or input events are generated.
3. keyup 'ر' ctrlKey Arabic Letter Reh
4. keyup 'Control'    

Note: The value in the keydown and keyup events varies based on the current keyboard layout in effect when the key is pressed. This means that the 'v' key on a US layout and the 'ر' key on an Arabic layout will generate different events even though they are the same physical key. To identify these events as coming from the same physical key, you will need to make use of the code attribute.

In some cases, modifier keys change the key value value for a key event. For example, on some MacOS keyboards, the key labeled 'delete' functions the same as the 'Backspace' key on the Windows OS when unmodified, but when modified by the 'Fn' key, acts as the 'Delete' key, and the value of the key value will match the most appropriate function of the key in its current modified state.

6.3.3 Dead keys

Some keyboard input uses dead keys for the input of composed character sequences. Unlike the handwriting sequence, in which users enter the base character first, keyboard input requires to enter a special state when a dead key is pressed and emit the character(s) only when one of a limited number of legal base character is entered.

Note: The MacOS and Linux operating systems use input methods to process dead keys.

The dead keys (across all keyboard layouts and mappings) are represented by the key value 'Dead'. In response to any dead key press, composition events must be dispatched by the user agent and the compositionupdate event's CompositionEvent.data value must be the character value of the current state of the dead key combining sequence.

While Unicode combining characters always follow the handwriting sequence, with the combining character trailing the corresponding letter, typical dead key input MAY reverse the sequence, with the combining character before the corresponding letter. For example, the word naïve, using the combining diacritic ¨, would be represented sequentially in Unicode as nai¨ve, but MAY be typed na¨ive. The sequence of keystrokes '\u0302' (Combining Circumflex Accent key) and '\u0065' (key marked with the Latin Small Letter E) will likely produce (on a French keyboard using a french mapping and without any modifier activated) the Unicode character 'ê' (Latin Small Letter E With Circumflex), as preferred by the Unicode Normalization Form NFC:

Note: The keydown and keyup events shown in these examples would normally be suppressed during the composition session. They are included in these examples to make the user actions (pressing and releasing keys) more apparent.

  Event NameKeyboardEvent
key		KeyboardEvent
isComposing		CompositionEvent
data		Notes
1. keydown 'Dead' false   Combining Circumflex Accent (Dead Key)
2. compositionstart     ''  
3. compositionupdate     '\u0302'  
4. keyup 'Dead' true    
5. keydown 'ê' true    
6. compositionupdate     'ê'  
7. compositionend     'ê'  
8. keyup 'e' false   Latin Small Letter E

Note: In the second keydown event (step 5), the key value (assuming the event is not suppressed) will not be 'e' (Latin Small Letter E key) under normal circumstances because the value delivered to the user agent will already be modified by the dead key operation.

This process might be aborted when a user types an unsupported base character (that is, a base character for which the which the active diacritical mark is not available) after pressing a dead key:

  Event NameKeyboardEvent
key		KeyboardEvent
isComposing		CompositionEvent
data		Notes
1. keydown 'Dead' false   Combining Circumflex Accent (Dead Key)
2. compositionstart     ''  
3. compositionupdate     '\u0302'  
4. keyup 'Dead' true    
5. keydown 'q' true   Latin Small Letter Q
6. compositionupdate     ''  
7. compositionend     ''  
8. keyup 'q' false    

6.3.4 Input Method Editors

This specification includes a model for input method editors (IMEs), through the CompositionEvent interface and events. However, Composition Events and Keyboard Events do not necessarily map as a one-to-one relationship. As an example, receiving a keydown for the 'Accept' key value does not necessarily imply that the text currently selected in the IME is being accepted, but indicates only that a keystroke happened, disconnected from the IME Accept functionality (which would normally result in a compositionend event in most IME systems). Keyboard events cannot be used to determine the current state of the input method editor, which can be obtained through the data attribute of the CompositionEvent interface. Additionally, IME systems and devices vary in their functionality, and in which keys are used for activating that functionality, such that the 'Convert' and 'Accept' keys MAY be represented by other available keys. Keyboard events correspond to the events generated by the input device after the keyboard layout mapping.

Note: In some implementations or system configurations, some key events, or their values, might be suppressed by the IME in use.

The following example describes a possible sequence of keys to generate the Unicode character '市' (Kanji character, part of CJK Unified Ideographs) using Japanese input methods. This example assumes that the input method editor is activated and in the Japanese-Romaji input mode. The keys 'Convert' and 'Accept' MAY be replaced by others depending on the input device in use and the configuration of the IME, e.g., it can be respectively '\u0020' (Space key) and 'Enter'.

Note: '詩' (poem) and '市' (city) are homophones, both pronounced し (shi), so the user needs to use the 'Convert' key to select the proper option.

  Event NameKeyboardEvent
key		KeyboardEvent
isComposing		CompositionEvent
data		Notes
1. keydown 's' false   Latin Small Letter S
2. compositionstart     ''  
3. compositionupdate     's'  
4. keyup 's' true    
5. keydown 'i' true   Latin Small Letter I
6. compositionupdate     'し'  
7. keyup 'i' true    
8. keydown 'Convert' true   Convert
9. compositionupdate     '詩'  
10. keyup 'Convert' true    
11. keydown 'Convert' true   Convert
12. compositionupdate     '市'  
13. keyup 'Convert' true    
14. keydown 'Accept' true   Accept
15. compositionend     '市'  
16. keyup 'Accept' false    

IME composition can also be canceled as in the following example, with conditions identical to the previous example. The key 'Cancel' might also be replaced by others depending on the input device in use and the configuration of the IME, e.g., it could be '\u001B' (Escape key).

  Event NameKeyboardEvent
key		KeyboardEvent
isComposing		CompositionEvent
data		Notes
1. keydown 's' false   Latin Small Letter S
2. compositionstart     ''  
3. compositionupdate     's'  
4. keyup 's' true    
5. keydown 'i' true   Latin Small Letter I
6. compositionupdate     'し'  
7. keyup 'i' true    
8. keydown 'Convert' true   Convert
9. compositionupdate     '詩'  
10. keyup 'Convert' true    
11. keydown 'Convert' true   Convert
12. compositionupdate     '市'  
13. keyup 'Convert' true    
14. keydown 'Cancel' true   Cancel
15. compositionupdate     ''  
16. compositionend     ''  
17. keyup 'Cancel' false    

Note: Some input method editors (such as on the MacOS operating system) might set an empty string to the composition data attribute before canceling a composition.

6.3.4.1 Input Method Editor mode keys

Some keys on certain devices are intended to activate input method editor functionality, or to change the mode of an active input method editor. Custom keys for this purpose can be defined for different devices or language modes. The keys defined in this specification for this purpose are: Alphanumeric, CodeInput, FinalMode, HangulMode, HanjaMode, Hiragana, JunjaMode, KanaMode, KanjiMode, Katakana, and RomanCharacters. When one of these keys is pressed, and no IME is currently active, the appropriate IME is expected to be activated in the mode indicated by the key (if available). If an IME is already active when the key is pressed, the active IME might change to the indicated mode, or a different IME might be launched, or the might MAY be ignored, on a device- and application-specific basis.

This specification also defines other keys which are intended for operation specifically with input method editors: Accept, AllCandidates, Cancel, Convert, Compose, FullWidth, HalfWidth, NextCandidate, Nonconvert, and PreviousCandidate. The functions of these keys are not defined in this specification — refer to other resources for details on input method editor functionality.

Note: Keys with input method editor functions are not restricted to that purpose, and can have other device- or implementation-specific purposes.

6.3.5 Default actions and cancelable keyboard events

Canceling the default action of a keydown event MUST NOT affect its respective keyup event, but it MUST prevent the respective beforeinput and input (and keypress if supported) events from being generated. The following example describes a possible sequence of keys to generate the Unicode character Q (Latin Capital Letter Q) on a US keyboard using a US mapping:

  Event NameKeyboardEvent
key		InputEvent
data		ModifiersNotes
1. keydown 'Shift'   shiftKey  
2. keydown 'Q'   shiftKey The default action is prevented, e.g., by invoking Event.preventDefault().
          No beforeinput or input (or keypress, if supported) events are generated
3. keyup 'Q'   shiftKey  
4. keyup 'Shift'      

If the key is a modifier key, the keystroke MUST still be taken into account for the modifiers states. The following example describes a possible sequence of keys to generate the Unicode character Q (Latin Capital Letter Q) on a US keyboard using a US mapping:

  Event NameKeyboardEvent
key		InputEvent
data		ModifiersNotes
1. keydown 'Shift'   shiftKey The default action is prevented, e.g., by invoking Event.preventDefault().
2. keydown 'Q'   shiftKey  
3. beforeinput   'Q'    
4. input        
5. keyup 'Q'   shiftKey  
6. keyup 'Shift'      

If the key is part of a sequence of several keystrokes, whether it is a dead key or it is contributing to an Input Method Editor sequence, the keystroke MUST be ignored (not taken into account) only if the default action is canceled on the keydown event. Canceling a dead key on a keyup event has no effect on beforeinput or input events. The following example uses the dead key 'Dead' ('\u0302' Combining Circumflex Accent key) and 'e' ('\u0065', Latin Small Letter E key) on a French keyboard using a French mapping and without any modifier activated:

  Event NameKeyboardEvent
key		InputEvent
data		Notes
1. keydown 'Dead'   The default action is prevented, e.g., by invoking Event.preventDefault().
2. keyup 'Dead'    
3. keydown 'e'    
4. beforeinput   'e'  
5. input      
6. keyup 'e'    

6.3.6 Guidelines for selecting key values

This section is normative.

To determine the appropriate key value for a key, use the following algorithm:

  1. If there exists an appropriate character in the key values set, then the KeyboardEvent.key attribute MUST be a string consisting of the key value of that character.
  2. If the key generates a printable character, and there exists an appropriate Unicode code point, then the KeyboardEvent.key attribute MUST be a string consisting of the char value of that character.
  3. If more than one key is being pressed and the key combination includes one or more modifier keys that result in the key no longer producing a printable character (e.g., 'Control' + 'a'), then the key value should be the printable key value that would have been produced if the key had been typed with the default keyboard layout with no modifier keys except for 'Shift' and 'AltGr' applied.
  4. Otherwise, the special value 'Unidentified' should be used.
  • On a US keyboard with a right-handed single-hand Dvorak key mapping, the key labeled 'Q' maps to the key values '5' (unmodified) and '%' (shifted). The primary function of this key is to generate the character '5' ('\u0035'). Since this character is a character (in Unicode general category Nd), the KeyboardEvent.key attribute value for the unmodified key will be '5'.
  • On the same US Dvorak keyboard layout as the previous example, pressing 'Control' and the key labeled 'Q' will produce a key value of 'q'.
  • On a French PC keyboard with a standard French mapping, the primary function of the '^' key is to act as a dead key for the combining circumflex diacritical mark. The value for this key is 'Dead'.
  • Also on a French PC keyboard with a standard French mapping, the 'é' key (which corresponds to the '2' key on a US keyboard) generates a key value of 'é' ('\u00e9').
  • On a Korean PC keyboard with a standard Korean mapping, the primary function of the 'Ha/En' key is to switch between Hangul and English input. The predefined key value list has an appropriate entry for this key, 'HangulMode', so this will be the key value.
  • On some mobile devices, there are special keys to launch specific applications. For a standard application like Calendar, there is a predefined key value of 'LaunchCalendar'.

While every attempt has been made to make this list of key values as complete as possible, new key values will periodically need to be defined as new input devices are introduced. Rather than allowing user agents to define their own key values (which may not work across multiple user agents), bugs should be filed so that this specification can be updated.

A. Legacy Event Initializers

This section is informative

Early versions of this specification included an initialization method on the interface (for example initMouseEvent) that required a long list of parameters that, in most cases, did not fully initialize all attributes of the event object. Because of this, event interfaces which were derived from the basic Event interface required that the initializer of each of the derived interfaces be called explicitly in order to fully initialize an event.

Initializing all the attributes of a MutationEvent requires calls to two initializer methods: initEvent and initMutationEvent.

Due in part to the length of time in the development of this standard, some implementations MAY have taken a dependency on these (now deprecated) initializer methods. For completeness, these legacy event intializers are described in this Appendix.

A.1 Legacy Event Initializer Interfaces

This section is informative

This section documents legacy initializer methods that were introduced in earlier versions of the DOM Level 3 Events specification.

A.1.1 Initializers for interface CustomEvent

partial interface CustomEvent {
    // Originally introduced (and deprecated) in DOM Level 3
    void initCustomEvent (DOMString typeArg, boolean bubblesArg, boolean cancelableArg, any detailArg);
};
A.1.1.1 Methods
initCustomEvent

Initializes attributes of a CustomEvent object. This method has the same behavior as Event.initEvent().

Warning! The initCustomEvent method is deprecated.

ParameterTypeNullableOptionalDescription
typeArg DOMString ✘ ✘

Refer to the Event.initEvent() method for a description of this parameter.
bubblesArg boolean ✘ ✘

Refer to the Event.initEvent() method for a description of this parameter.
cancelableArg boolean ✘ ✘

Refer to the Event.initEvent() method for a description of this parameter.
detailArg any ✘ ✘

Specifies CustomEvent.detail.
Return type: void

A.1.2 Initializers for interface UIEvent

partial interface UIEvent {
    // Deprecated in DOM Level 3
    void initUIEvent (DOMString typeArg, boolean bubblesArg, boolean cancelableArg, Window? viewArg, long detailArg);
};
A.1.2.1 Methods
initUIEvent

Initializes attributes of an UIEvent object. This method has the same behavior as Event.initEvent().

Warning! The initUIEvent method is deprecated, but supported for backwards-compatibility with widely-deployed implementations.

ParameterTypeNullableOptionalDescription
typeArg DOMString ✘ ✘

Refer to the Event.initEvent() method for a description of this parameter.
bubblesArg boolean ✘ ✘

Refer to the Event.initEvent() method for a description of this parameter.
cancelableArg boolean ✘ ✘

Refer to the Event.initEvent() method for a description of this parameter.
viewArg Window ✔ ✘

Specifies UIEvent.view. This value MAY be null.
detailArg long ✘ ✘

Specifies UIEvent.detail.
Return type: void

A.1.3 Initializers for interface FocusEvent

partial interface FocusEvent {
    // Originally introduced (and deprecated) in DOM Level 3
    void initFocusEvent (DOMString typeArg, boolean bubblesArg, boolean cancelableArg, Window? viewArg, long detailArg, EventTarget? relatedTargetArg);
};
A.1.3.1 Methods
initFocusEvent

Initializes attributes of a FocusEvent object. This method has the same behavior as UIEvent.initUIEvent().

Warning! The initFocusEvent method is deprecated.

ParameterTypeNullableOptionalDescription
typeArg DOMString ✘ ✘

Refer to the UIEvent.initUIEvent() method for a description of this parameter.
bubblesArg boolean ✘ ✘

Refer to the UIEvent.initUIEvent() method for a description of this parameter.
cancelableArg boolean ✘ ✘

Refer to the UIEvent.initUIEvent() method for a description of this parameter.
viewArg Window ✔ ✘

Refer to the UIEvent.initUIEvent() method for a description of this parameter.
detailArg long ✘ ✘

Refer to the UIEvent.initUIEvent() method for a description of this parameter.
relatedTargetArg EventTarget ✔ ✘

Specifies FocusEvent.relatedTarget. This value MAY be null.
Return type: void

A.1.4 Initializers for interface MouseEvent

partial interface MouseEvent {
    // Deprecated in DOM Level 3
    void initMouseEvent (DOMString typeArg, boolean bubblesArg, boolean cancelableArg, Window? viewArg, long detailArg, long screenXArg, long screenYArg, long clientXArg, long clientYArg, boolean ctrlKeyArg, boolean altKeyArg, boolean shiftKeyArg, boolean metaKeyArg, short buttonArg, EventTarget? relatedTargetArg);
};
A.1.4.1 Methods
initMouseEvent

Initializes attributes of a MouseEvent object. This method has the same behavior as UIEvent.initUIEvent().

Warning! The initMouseEvent method is deprecated, but supported for backwards-compatibility with widely-deployed implementations.

ParameterTypeNullableOptionalDescription
typeArg DOMString ✘ ✘

Refer to the UIEvent.initUIEvent() method for a description of this parameter.
bubblesArg boolean ✘ ✘

Refer to the UIEvent.initUIEvent() method for a description of this parameter.
cancelableArg boolean ✘ ✘

Refer to the UIEvent.initUIEvent() method for a description of this parameter.
viewArg Window ✔ ✘

Refer to the UIEvent.initUIEvent() method for a description of this parameter.
detailArg long ✘ ✘

Refer to the UIEvent.initUIEvent() method for a description of this parameter.
screenXArg long ✘ ✘

Specifies MouseEvent.screenX.
screenYArg long ✘ ✘

Specifies MouseEvent.screenY.
clientXArg long ✘ ✘

Specifies MouseEvent.clientX.
clientYArg long ✘ ✘

Specifies MouseEvent.clientY.
ctrlKeyArg boolean ✘ ✘

Specifies MouseEvent.ctrlKey.
altKeyArg boolean ✘ ✘

Specifies MouseEvent.altKey.
shiftKeyArg boolean ✘ ✘

Specifies MouseEvent.shiftKey.
metaKeyArg boolean ✘ ✘

Specifies MouseEvent.metaKey.
buttonArg short ✘ ✘

Specifies MouseEvent.button.
relatedTargetArg EventTarget ✔ ✘

Specifies MouseEvent.relatedTarget. This value MAY be null.
Return type: void

A.1.5 Initializers for interface WheelEvent

partial interface WheelEvent {
    // Originally introduced (and deprecated) in DOM Level 3
    void initWheelEvent (DOMString typeArg, boolean bubblesArg, boolean cancelableArg, Window? viewArg, long detailArg, long screenXArg, long screenYArg, long clientXArg, long clientYArg, short buttonArg, EventTarget? relatedTargetArg, DOMString modifiersListArg, double deltaXArg, double deltaYArg, double deltaZArg, unsigned long deltaMode);
};
A.1.5.1 Methods
initWheelEvent

Initializes attributes of a WheelEvent object. This method has the same behavior as MouseEvent.initMouseEvent().

Warning! The initWheelEvent method is deprecated.

ParameterTypeNullableOptionalDescription
typeArg DOMString ✘ ✘

Refer to the UIEvent.initUIEvent() method for a description of this parameter.
bubblesArg boolean ✘ ✘

Refer to the UIEvent.initUIEvent() method for a description of this parameter.
cancelableArg boolean ✘ ✘

Refer to the UIEvent.initUIEvent() method for a description of this parameter.
viewArg Window ✔ ✘

Refer to the UIEvent.initUIEvent() method for a description of this parameter.
detailArg long ✘ ✘

Refer to the UIEvent.initUIEvent() method for a description of this parameter.
screenXArg long ✘ ✘

Refer to the MouseEvent.initMouseEvent() method for a description of this parameter.
screenYArg long ✘ ✘

Refer to the MouseEvent.initMouseEvent() method for a description of this parameter.
clientXArg long ✘ ✘

Refer to the MouseEvent.initMouseEvent() method for a description of this parameter.
clientYArg long ✘ ✘

Refer to the MouseEvent.initMouseEvent() method for a description of this parameter.
buttonArg short ✘ ✘

Refer to the MouseEvent.initMouseEvent() method for a description of this parameter.
relatedTargetArg EventTarget ✔ ✘

Refer to the MouseEvent.initMouseEvent() method for a description of this parameter.
modifiersListArg DOMString ✘ ✘

A white space separated list of modifier key values to be activated on this object. As an example, "Control Shift" marks the control and shift modifiers as activated (the MouseEvent.ctrlKey and MouseEvent.shiftKey inherited attributes will be true on the initialized WheelEvent object).
deltaXArg double ✘ ✘

Specifies WheelEvent.deltaX.
deltaYArg double ✘ ✘

Specifies WheelEvent.deltaY.
deltaZArg double ✘ ✘

Specifies WheelEvent.deltaZ.
deltaMode unsigned long ✘ ✘

Specifies WheelEvent.deltaMode.
Return type: void

A.1.6 Initializers for interface KeyboardEvent

Note: The argument list to this legacy KeyboardEvent initializer does not include the detailArg (present in other initializers) and adds the locale argument (see Changes between different drafts of DOM Level 3 Events); it is necessary to preserve this inconsistency for compatibility with existing implementations.

partial interface KeyboardEvent {
    // Originally introduced (and deprecated) in DOM Level 3
    void initKeyboardEvent (DOMString typeArg, boolean bubblesArg, boolean cancelableArg, Window? viewArg, DOMString keyArg, unsigned long locationArg, DOMString modifiersListArg, boolean repeat, DOMString locale);
};
A.1.6.1 Methods
initKeyboardEvent

Initializes attributes of a KeyboardEvent object. This method has the same behavior as UIEvent.initUIEvent(). The value of UIEvent.detail remains undefined.

Warning! The initKeyboardEvent method is deprecated.

ParameterTypeNullableOptionalDescription
typeArg DOMString ✘ ✘

Refer to the UIEvent.initUIEvent() method for a description of this parameter.
bubblesArg boolean ✘ ✘

Refer to the UIEvent.initUIEvent() method for a description of this parameter.
cancelableArg boolean ✘ ✘

Refer to the UIEvent.initUIEvent() method for a description of this parameter.
viewArg Window ✔ ✘

Refer to the UIEvent.initUIEvent() method for a description of this parameter.
keyArg DOMString ✘ ✘

Specifies KeyboardEvent.key.
locationArg unsigned long ✘ ✘

Specifies KeyboardEvent.location.
modifiersListArg DOMString ✘ ✘

A white space separated list of modifier key values to be activated on this object. As an example, "Control Alt" marks the control and alt modifiers as activated.
repeat boolean ✘ ✘

Specifies whether the key event is repeating. See KeyboardEvent.repeat.
locale DOMString ✘ ✘

Specifies the locale attribute of the KeyboardEvent. This attribute is not defined in DOM3, but will be included in the [UI Events] specification. User agents which do not support locale should ignore this parameter.
Return type: void

A.1.7 Initializers for interface CompositionEvent

Note: The argument list to this legacy CompositionEvent initializer does not include the detailArg (present in other initializers) and adds the locale argument (see Changes between different drafts of DOM Level 3 Events); it is necessary to preserve this inconsistency for compatibility with existing implementations.

partial interface CompositionEvent {
    // Originally introduced (and deprecated) in DOM Level 3
    void initCompositionEvent (DOMString typeArg, boolean bubblesArg, boolean cancelableArg, Window? viewArg, DOMString dataArg, DOMString locale);
};
A.1.7.1 Methods
initCompositionEvent

Initializes attributes of a CompositionEvent object. This method has the same behavior as UIEvent.initUIEvent(). The value of UIEvent.detail remains undefined.

Warning! The initCompositionEvent method is deprecated.

ParameterTypeNullableOptionalDescription
typeArg DOMString ✘ ✘

Refer to the UIEvent.initUIEvent() method for a description of this parameter.
bubblesArg boolean ✘ ✘

Refer to the UIEvent.initUIEvent() method for a description of this parameter.
cancelableArg boolean ✘ ✘

Refer to the UIEvent.initUIEvent() method for a description of this parameter.
viewArg Window ✔ ✘

Refer to the UIEvent.initUIEvent() method for a description of this parameter.
dataArg DOMString ✘ ✘

Specifies CompositionEvent.data.
locale DOMString ✘ ✘

Specifies the locale attribute of the CompositionEvent. This attribute is not defined in DOM3, but will be included in the [UI Events] specification. User agents which do not support locale should ignore this parameter.
Return type: void

B. Legacy Key Attributes

This section is informative

This section provides a non-normative description of the attributes that are currently used when handling keyboard events.

These features were never formally specified and the current browser implementations vary in significant ways. The large amount of legacy content, including script libraries, that relies upon detecting the user agent and acting accordingly means that any attempt to formalize these legacy attributes and events would risk breaking as much content as it would fix or enable. Additionally, these attributes are not suitable for international usage, nor do they address accessibility concerns.

Therefore, this specification does not normatively define the events and attributes commonly employed for handling keyboard input, though they MAY be present in user agents for compatibility with legacy content. Authors SHOULD use the KeyboardEvent.key attribute instead of the charCode and keyCode attributes.

However, for the purpose of documenting the current state of these features and their relation to normative events and attributes, this section provides an informative description. For implementations which do support these attributes and events, it is suggested that the definitions provided in this section be used.

B.1 Legacy KeyboardEvent supplemental interface

This section is informative

Browser support for keyboards has traditionally relied on three ad-hoc attributes, keyCode, charCode, and which.

All three of these attributes return a numerical code that represents some aspect of the key pressed: keyCode is an index of the key itself. charCode is the ASCII value of the character keys. which is the character value where available and otherwise the key index. The values for these attributes, and the availability of the attribute, is inconsistent across platforms, keyboard languages and layouts, user agents, versions, and even event types.

Interface KeyboardEvent (supplemental)

Introduced in DOM Level 3

The partial KeyboardEvent interface is an informative extension of the KeyboardEvent interface, which adds the charCode, keyCode, and which attributes.

The partial KeyboardEvent interface can be obtained by using the DocumentEvent.createEvent("KeyboardEvent") method call in implementations that support this extension.

partial interface KeyboardEvent {
    // The following support legacy user agents
    readonly    attribute unsigned long charCode;
    readonly    attribute unsigned long keyCode;
    readonly    attribute unsigned long which;
};

Attributes

charCode of type unsigned long, readonly

charCode holds a character value, for keypress events which generate character input. The value is the Unicode reference number (code point) of that character (e.g. event.charCode = event.key.charCodeAt(0) for printable characters). For keydown or keyup events, the value of charCode is 0.

keyCode of type unsigned long, readonly

keyCode holds a system- and implementation-dependent numerical code signifying the unmodified identifier associated with the key pressed. Unlike the KeyboardEvent.key attribute, the set of possible values are not normatively defined in this specification. Typically, these value of the keyCode SHOULD represent the decimal codepoint in ASCII [RFC20][US-ASCII] or Windows 1252 [WIN1252], but MAY be drawn from a different appropriate character set. Implementations that are unable to identify a key use the key value '0'.

See Legacy key models for more details on how to determine the values for keyCode.

which of type unsigned long, readonly

which holds a system- and implementation-dependent numerical code signifying the unmodified identifier associated with the key pressed. In most cases, the value is identical to keyCode.

dictionary KeyboardEventInit (supplemental)

Browsers that include support for keyCode, charCode, and which in KeyboardEvent should also add the following members to the KeyboardEventInit dictionary.

The partial KeyboardEventInit dictionary is an informative extension of the KeyboardEventInit dictionary, which adds charCode, keyCode, and which members to initialize the corresponding KeyboardEvent attributes.

partial dictionary KeyboardEventInit {
    unsigned long charCode = 0;
    unsigned long keyCode = 0;
    unsigned long which = 0;
};

Dictionary KeyboardEventInit Members

charCode of type unsigned long, defaulting to 0

Initializes the charCode attribute of the KeyboardEvent to the Unicode code point for the event's character.

keyCode of type unsigned long, defaulting to 0

Initializes the keyCode attribute of the KeyboardEvent to the system- and implementation-dependent numerical code signifying the unmodified identifier associated with the key pressed.

which of type unsigned long, defaulting to 0

Initializes the which attribute of the KeyboardEvent to the implementation-dependent numerical code signifying the unmodified identifier associated with the key pressed. In most cases, the value is identical to keyCode.

B.2 Legacy key models

This section is informative

Implementations differ on which values are exposed on these attributes for different event types. An implementation MAY choose to expose both virtual key codes and character codes in the keyCode property (conflated model), or report separate keyCode and charCode properties (split model).

B.2.1 How to determine keyCode for keydown and keyup events

The keyCode for keydown or keyup events is calculated as follows:

  1. Read the virtual key code from the operating system's event information, if such information is available.
  2. If an Input Method Editor is processing key input and the event is keydown, return 229.
  3. If input key when pressed without modifiers would insert a numerical character (0-9), return the ASCII code of that numerical character.
  4. If input key when pressed without modifiers would insert a lower case character in the a-z alphabetical range, return the ASCII code of the upper case equivalent.
  5. If the implementation supports a key code conversion table for the operating system and platform, look up the value. If the conversion table specifies an alternate virtual key value for the given input, return the specified value.
  6. If the key's function, as determined in an implementation-specific way, corresponds to one of the keys in the table of fixed virtual key codes, return the corresponding key code.
  7. Return the virtual key code from the operating system.
  8. If no key code was found, return 0.

B.2.2 How to determine keyCode for keypress events

The keyCode for keypress events is calculated as follows:

  1. If the implementation supports a conflated model, set keyCode to the Unicode code point of the character being entered.
  2. If the implementation supports a split model, set keyCode to 0.

B.2.3 Fixed virtual key codes

The virtual key codes for the following keys do not usually change with keyboard layouts on desktop systems:

KeyVirtual Key
Code		Notes
'Backspace' 8  
'Tab' 9  
'Enter' 13  
'Shift' 16  
'Control' 17  
'Alt' 18  
'CapsLock' 20  
'Escape' 27 Esc
' ' 32 Space
'PageUp' 33  
'PageDown' 34  
'End' 35  
'Home' 36  
'ArrowLeft' 37  
'ArrowUp' 38  
'ArrowRight' 39  
'ArrowDown' 40  
'Delete' 46 Del

B.2.4 Optionally fixed virtual key codes

The following punctuation characters MAY change virtual codes between keyboard layouts, but reporting these values will likely be more compatible with legacy content expecting US-English keyboard layout:

KeyCharacterVirtual Key
Code
Semicolon ';' 186
Colon ':' 186
Equals sign '=' 187
Plus '+' 187
Comma ',' 188
Less than sign '<' 188
Minus '-' 189
Underscore '_' 189
Period '.' 190
Greater than sign '>' 190
Forward slash '/' 191
Question mark '?' 191
Backtick '`' 192
Tilde '~' 192
Opening square bracket '[' 219
Opening curly brace '{' 219
Backslash '\' 220
Pipe '|' 220
Closing square bracket ']' 221
Closing curly brace '}' 221
Single quote ''' 222
Double quote '"' 222

C. Legacy Event Types

This section is informative

This section provides a non-normative description of the event types that are deprecated in this document.

The purpose of this section is to document the current state of these features and their relation to normative events. For implementations which do support these events, it is suggested that the definitions provided in this section be used.

The following table provides an informative summary of the event types which are deprecated in this specification. They are included here for reference and completeness.

Event TypeSync / AsyncBubbling phaseTrusted event target typesDOM interfaceCancelableDefault Action
DOMActivate Sync Yes Element UIEvent Yes None
DOMAttrModified Sync Yes Element MutationEvent No None
DOMCharacterDataModified Sync Yes Text, Comment, ProcessingInstruction MutationEvent No None
DOMFocusIn Sync Yes Window, Element FocusEvent No None
DOMFocusOut Sync Yes Window, Element FocusEvent No None
DOMNodeInserted Sync Y
posted @ 2015-03-14 22:40  Raffeale  阅读(1494)  评论(0)  编辑  收藏  举报