jQuery Pocket Reference

The jQuery Event Object

jQuery hides implementation differences among browsers by defining its own Event object. When a jQuery event handler is invoked, it is always passed a jQuery Event object as its first argument. The jQuery Event object is based heavily on W3C standards, but it also codifies some de-facto event standards. jQuery does not define a hierarchy of Event object types, for example, there are not separate Event, MouseEvent, and KeyEvent types. jQuery copies all of the following fields from the native Event object into every jQuery Event object (though some of them will be undefined for certain event types):

altKey        ctrlKey         newValue        screenX
attrChange    currentTarget   offsetX         screenY
attrName      detail          offsetY         shiftKey
bubbles       eventPhase      originalTarget  srcElement
button        fromElement     pageX           target
cancelable    keyCode         pageY           toElement
charCode      layerX          prevValue       view
clientX       layerY          relatedNode     wheelDelta
clientY       metaKey         relatedTarget   which

In addition to these properties, the Event object also defines the following methods:

preventDefault()           isDefaultPrevented()
stopPropagation()          isPropagationStopped()
stopImmediatePropagation() isImmediatePropagationStopped()

Most of these event properties and methods are standardized by the W3C, and you can read about them in any JavaScript reference. Some of these fields, shown in the following list, are specially handled by jQuery to give them a uniform cross-browser behavior:

metaKey

If the native event object does not have a metaKey property, jQuery sets this to the same value as the ctrlKey property. In MacOS, the Command key sets the metaKey property.

pageX, pageY

If the native event object does not define these properties but does define the viewport coordinates of the mouse pointer in clientX and clientY, jQuery computes the document coordinates of the mouse pointer and stores them in pageX and pageY.

target, currentTarget, relatedTarget

The target property is the document element on which the event occurred. If the native event object has a text node as the target, jQuery reports the containing Element instead. currentTarget is the element on which the current executing event handler was registered. This should always be the same as this.

If currentTarget is not the same as target, you’re handling an event that has bubbled up from the element on which it occurred, and it may be useful to test the target element with the is() method (see Queries and Query Results):

// Ignore events that start on links
if ($(event.target).is("a")) return; 

relatedTarget is the other element involved in transition events such as “mouseover” and “mouseout”. For “mouseover” events, for example, the relatedTarget property specifies the element that the mouse pointer exited as it moved over the target. If the native event object does not define relatedTarget but does define toElement and fromElement, relatedTarget is set from those properties.

timeStamp

The time at which the event occurred, in the millisecond representation returned by the Date.getTime() method. jQuery sets the field itself to work around a long-standing bug in Firefox.

which

jQuery normalizes this nonstandard event property so that it specifies which mouse button or keyboard key was pressed during the event. For keyboard events, if the native event does not define which but defines charCode or keyCode, then which will be set to whichever of those properties is defined. For mouse events, if which is not defined but the button property is defined, which is set based on the button value: 0 means no buttons are pressed, 1 means the left button is pressed, 2 means the middle button is pressed, and 3 means the right button is pressed. (Note that some browsers don’t generate mouse events for right-button clicks.)

In addition, the following fields of the jQuery Event object are jQuery-specific additions that you may sometimes find useful:

data

If additional data was specified when the event handler was registered (see ), it is made available to the handler as the value of this field.

handler

A reference to the event handler function currently being invoked.

result

The return value of the most recently invoked handler for this event, ignoring handlers that do not return a value.

originalEvent

A reference to the native Event object generated by the browser.