Version: v7.x

Interaction

PixiJS is primarily a rendering system, but it also includes support for interactivity. Adding support for mouse and touch events to your project is simple and consistent.

Event Modes

The new event-based system that replaced InteractionManager from v6 has expanded the definition of what a DisplayObject means to be interactive. With this we have introduced eventMode which allows you to control how an object responds to interaction events. This is similar to the interactive property in v6 but with more options.

eventMode	Description
`none`	Ignores all interaction events, similar to CSS's `pointer-events: none`, good optimization for non-interactive children
`passive`	Does not emit events and ignores hit testing on itself but does allow for events and hit testing only its interactive children. If you want to be compatible with v6, set this as your default `eventMode` (see options in Renderer, Application, etc)
`auto`	Does not emit events and but is hit tested if parent is interactive. Same as `interactive = false` in v7
`static`	Emit events and is hit tested. Same as `interaction = true` in v7, useful for objects like buttons that do not move.
`dynamic`	Emits events and is hit tested but will also receive mock interaction events fired from a ticker to allow for interaction when the mouse isn't moving. This is useful for elements that independently moving or animating.

Event Types

PixiJS supports the following event types:

Event Type	Description
`pointercancel`	Fired when a pointer device button is released outside the display object that initially registered a pointerdown.
`pointerdown`	Fired when a pointer device button is pressed on the display object.
`pointerenter`	Fired when a pointer device enters the display object.
`pointerleave`	Fired when a pointer device leaves the display object.
`pointermove`	Fired when a pointer device is moved while over the display object.
`globalpointermove`	Fired when a pointer device is moved, regardless of hit-testing the current object.
`pointerout`	Fired when a pointer device is moved off the display object.
`pointerover`	Fired when a pointer device is moved onto the display object.
`pointertap`	Fired when a pointer device is tapped on the display object.
`pointerup`	Fired when a pointer device button is released over the display object.
`pointerupoutside`	Fired when a pointer device button is released outside the display object that initially registered a pointerdown.
`mousedown`	Fired when a mouse button is pressed on the display object.
`mouseenter`	Fired when the mouse cursor enters the display object.
`mouseleave`	Fired when the mouse cursor leaves the display object.
`mousemove`	Fired when the mouse cursor is moved while over the display object.
`globalmousemove`	Fired when a mouse is moved, regardless of hit-testing the current object.
`mouseout`	Fired when the mouse cursor is moved off the display object.
`mouseover`	Fired when the mouse cursor is moved onto the display object.
`mouseup`	Fired when a mouse button is released over the display object.
`mouseupoutside`	Fired when a mouse button is released outside the display object that initially registered a mousedown.
`click`	Fired when a mouse button is clicked (pressed and released) over the display object.
`touchcancel`	Fired when a touch point is removed outside of the display object that initially registered a touchstart.
`touchend`	Fired when a touch point is removed from the display object.
`touchendoutside`	Fired when a touch point is removed outside of the display object that initially registered a touchstart.
`touchmove`	Fired when a touch point is moved along the display object.
`globaltouchmove`	Fired when a touch point is moved, regardless of hit-testing the current object.
`touchstart`	Fired when a touch point is placed on the display object.
`tap`	Fired when a touch point is tapped on the display object.
`wheel`	Fired when a mouse wheel is spun over the display object.
`rightclick`	Fired when a right mouse button is clicked (pressed and released) over the display object.
`rightdown`	Fired when a right mouse button is pressed on the display object.
`rightup`	Fired when a right mouse button is released over the display object.
`rightupoutside`	Fired when a right mouse button is released outside the display object that initially registered a rightdown.

Enabling Interaction

Any DisplayObject-derived object (Sprite, Container, etc.) can become interactive simply by setting its eventMode property to any of the eventModes listed above. Doing so will cause the object to emit interaction events that can be responded to in order to drive your project's behavior.

Check out the interaction example code.

To respond to clicks and taps, bind to the events fired on the object, like so:

let sprite = PIXI.Sprite.from('/some/texture.png');
sprite.on('pointerdown', (event) => { alert('clicked!'); });
sprite.eventMode = 'static';

Check out the DisplayObject for the list of interaction events supported.

Checking if Object is Interactive

You can check if an object is interactive by calling the isInteractive property. This will return true if eventMode is set to static or dynamic.

if (sprite.isInteractive()) {
    // sprite is interactive
}

Use Pointer Events

PixiJS supports three types of interaction events - mouse, touch and pointer. Mouse events are fired by mouse movement, clicks etc. Touch events are fired for touch-capable devices. And pointer events are fired for both.

What this means is that, in many cases, you can write your project to use pointer events and it will just work when used with either mouse or touch input. Given that, the only reason to use non-pointer events is to support different modes of operation based on input type or to support multi-touch interaction. In all other cases, prefer pointer events.

Optimization

Hit testing requires walking the full object tree, which in complex projects can become an optimization bottleneck. To mitigate this issue, PixiJS Container-derived objects have a property named interactiveChildren. If you have Containers or other objects with complex child trees that you know will never be interactive, you can set this property to false and the hit testing algorithm will skip those children when checking for hover and click events. As an example, if you were building a side-scrolling game, you would probably want to set background.interactiveChildren = false for your background layer with rocks, clouds, flowers, etc. Doing so would speed up hit testing substantially due to the number of unclickable child objects the background layer would contain.

The EventSystem can also be customised to be more performant:

const app = new PIXI.Application({
    /**
     * by default we use `auto` for backwards compatibility.
     * However `passive` is more performant and will be used by default in the future,
     */
    eventMode: 'passive',
    eventFeatures: {
        move: true,
        /** disables the global move events which can be very expensive in large scenes */
        globalMove: false,
        click: true,
        wheel: true,
    }
});

Event Modes​

Event Types​

Enabling Interaction​

Checking if Object is Interactive​

Use Pointer Events​