Dojo FAQ: Why doesn’t my mouse event have pageX/Y or layerX/Y? Doesn’t Dojo normalize events?

By on May 22, 2013 12:30 pm

Position properties on mouse events

The W3 specification for DOM events includes clientX/Y and screenX/Y properties on MouseEvents, but pageX/Y, layerX/Y, and offsetX/Y are non-standard properties. They are occasionally useful though and have fairly widespread browser support, even if they are a bit inconsistent.

The chief danger is with layerX/Y and offsetX/Y. They should report the position of the cursor relative to the origin of the closest enclosing element that is positioned, but not all browsers agree on what qualifies as a “positioned” element.

Dojo’s Extra Event Normalization to the Rescue

Using Dojo, you may have grown accustomed to, and fond of, Dojo’s event normalization – regardless of browser, you can register your event handlers in a consistent way with dojo/on, and rely on a consistent set of properties and methods, like event.relatedTarget and event.preventDefault(). Given that, you may be surprised to discover that cursor position properties are not normalized!

This gap in normalization is intentional because it can be costly to calculate these properties which are often not needed. Dojo does provide a method for normalizing these properties, but you must call it explicitly when you need them. The dojo/dom-geometry module has a normalizeEvent method that sets layerX/Y (if they’re not already present) to offsetX/Y. Additionally, if pageX/Y are not present, they are calculated and set.

Something to watch out for: the offsetX/Y properties are not set (even if missing), and they are not provided in Firefox (Firefox 21 at the time of writing).

In Closing

Before working with low-level details like these properties, you should see if there’s a higher-level abstraction that will serve your purpose. Dojo’s dojo/dom-geometry module has numerous position and geometry-related methods (like position). The DOM method elementFromPoint (even supported in IE8!) will give you the DOM element at the specified X/Y coordinates. Consider using one of these approaches instead of relying on the non-standard properties.