The new input event type introduced in this document provides web developers a way to listen to the "click" behavior of non-primary buttons, and potentially cancel their effect (eg. opening a new tab when middle clicking on a link). This new input type is needed because the click event is restricted to primary button only.

This proposal was first introduced in this discourse.

Introduction

Traditionally some users agents (eg. Chrome, Safari and Edge) have fired the click event for all buttons (including non-primary). This poses a number of issues with pages executing click event handlers where the developer hasn't considered non-primary-button scenarios (for example, middle-click failing to open links in a new tab is a commmon source of user complaints in these browsers). Other user agents have followed different a approaches here. Firefox dispatches non-primary-button clicks event only to the document level nodes.

For maximum compatibility with existing click handlers (which mostly do not consider non-primary button scenarios), the click event is defined to fire only for the primary button. However some applications may still wish to override the default behavior of the UA for non-primary button clicks. Specifically it is desirable to have an event for the middle button and explicitly define the default behavior.

The auxclick event

The proposed solution to the problem above is a new MouseEvent (as defined in [[!UIEvents]]) of type auxclick which is dispatched for all non-primary buttons. This event is not only dispatched for middle button but also covers click for other buttons. It should be targeted at the node (i.e. common ancestor of mousedown and mouseup targets) and bubble as the click event does.

Click events are special in terms of allowing untrusted default action behavior for legacy purposes. It is believe that untrusted auxclick events should be are treated purely as untrusted and must not run the default action behavior. Since we are changing the type from click to auxclick but keeping all other semantics the same, we believe only minor changes to applications that are currently using this behavior would be required.

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

The auxclick event type MUST be dispatched on the topmost event target indicated by the pointer, when the user presses down and releases the non-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.

The auxclick event should only be fired for the non-primary pointer buttons (i.e., when MouseEvent.button value is not 0, MouseEvent.buttons value is greater than 1). Primary button (like the left button a standard mouse) MUST NOT fire auxclick events. See click event for the primary button.

The auxclick 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 auxclick 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 default action of the auxclick 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 auxclick event type are as follows:

In the case of right button, the auxclick event is dispatched after any contextmenu event. See this example for more clarification.

Extensions to the GlobalEventHandlers interface

The following section describes extensions to the existing GlobalEventHandlers interface, defined in [[!HTML5]], to facilitate the event handler registration.

partial interface GlobalEventHandlers {
    attribute EventHandler onauxclick;
};
            
onauxclick
The event handler IDL attribute (see [[!HTML5]]) for the auxclick event type.

Examples

The following are examples that demonstrate how the new event in this specification might be used

      myLink.addEventListener('auxclick', function(e) {
        if (e.button === 1) {
          // This would prevent the default behavior which is for example
          // opening a new tab when middle clicking on a link.
          e.preventDefault();

          // Do something else to handle middle button click like taking
          // care of opening link or non-link buttons in new tabs in a way
          // that fits the app. Other actions like closing a tab in a tab-strip
          // which should be done on the click action can be done here too.
        }
      });
      
      myDiv.addEventListener('contextmenu', function(e) {
        // This call makes sure no context menu is shown
        // to interfere with page receiving the events.
        e.preventDefault();
      });
      myDiv.addEventListener('auxclick', function(e) {
        if (e.button === 2) {
          // Do something else to handle right button click like opening a
          // customized context menu inside the app.
        }
      });