Namespace: events

events

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.

The new event-based system that replaced InteractionManager from v6 has expanded the definition of what a Container 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.

Enabling Interaction

Any Container-derived object (Sprite, Container, etc.) can become interactive simply by setting its eventMode property to any of the EventMode values. 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.

Container-derived objects are based on EventEmitter3 so you can use on(), once(), off() to listen to events.

For example to respond to clicks and taps, bind to an object ike so:

let sprite = Sprite.from('/some/texture.png');

sprite.eventMode = 'static'; // similar to `sprite.interactive = true` in v6
sprite.on('pointerdown', (event) => { alert('clicked!'); });

Check out the EventTypes section below for the full list of interaction events supported.

Event Modes

event mode	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

Pixi supports the following event types for interactive objects:

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

Classes

EventBoundary
EventsTicker
EventSystem
FederatedEvent
FederatedMouseEvent
FederatedPointerEvent
FederatedWheelEvent

Interface Definitions

EventSystemFeatures

The event features that are enabled by the EventSystem (included in the pixi.js and pixi.js-legacy bundle), otherwise it will be ignored.

Properties:

Name	Type	Description
`click`	boolean	Enables pointer events associated with clicking: `pointerup` / `mouseup` / `touchend` / 'rightup' `pointerupoutside` / `mouseupoutside` / `touchendoutside` / 'rightupoutside' `pointerdown` / 'mousedown' / `touchstart` / 'rightdown' `click` / `tap`
`globalMove`	boolean	Enables global pointer move events: `globalpointermove` `globalmousemove` `globaltouchemove`
`move`	boolean	Enables pointer events associated with pointer movement: `pointermove` / `mousemove` / `touchmove` `pointerout` / `mouseout` `pointerover` / `mouseover`
`wheel`	boolean	Enables wheel events.

Since:

7.2.0

FederatedEventTarget Deprecated : since 8.1.4

A simplified shape of an interactive object for the eventTarget property of a FederatedEvent

Properties:

Name	Type	Description
`children`	ReadonlyArray<FederatedEventTarget>	The children of this event target.
`isInteractive`	() => boolean	Returns true if the Container has interactive 'static' or 'dynamic'
`parent`	FederatedEventTarget	The parent of this event target.

FederatedOptions

The properties available for any interactive object.

Properties:

Name	Type	Description
`cursor`	Cursor \| string	The cursor preferred when the mouse pointer is hovering over.
`eventMode`	EventMode	The mode of interaction for this object
`hitArea`	IHitArea \| null	The hit-area specifies the area for which pointer events should be captured by this event target.
`interactive`	boolean	Whether this event target should fire UI events.
`interactiveChildren`	boolean	Whether this event target has any children that need UI events. This can be used optimize event propagation.
`onclick`	FederatedEventHandler \| null	Handler for 'click' event
`onglobalmousemove`	FederatedEventHandler \| null	Handler for 'globalmousemove' event
`onglobalpointermove`	FederatedEventHandler \| null	Handler for 'globalpointermove' event
`onglobaltouchmove`	FederatedEventHandler \| null	Handler for 'globaltouchmove' event
`onmousedown`	FederatedEventHandler \| null	Handler for 'mousedown' event
`onmouseenter`	FederatedEventHandler \| null	Handler for 'mouseenter' event
`onmouseleave`	FederatedEventHandler \| null	Handler for 'mouseleave' event
`onmousemove`	FederatedEventHandler \| null	Handler for 'mousemove' event
`onmouseout`	FederatedEventHandler \| null	Handler for 'mouseout' event
`onmouseover`	FederatedEventHandler \| null	Handler for 'mouseover' event
`onmouseup`	FederatedEventHandler \| null	Handler for 'mouseup' event
`onmouseupoutside`	FederatedEventHandler \| null	Handler for 'mouseupoutside' event
`onpointercancel`	FederatedEventHandler \| null	Handler for 'pointercancel' event
`onpointerdown`	FederatedEventHandler \| null	Handler for 'pointerdown' event
`onpointerenter`	FederatedEventHandler \| null	Handler for 'pointerenter' event
`onpointerleave`	FederatedEventHandler \| null	Handler for 'pointerleave' event
`onpointermove`	FederatedEventHandler \| null	Handler for 'pointermove' event
`onpointerout`	FederatedEventHandler \| null	Handler for 'pointerout' event
`onpointerover`	FederatedEventHandler \| null	Handler for 'pointerover' event
`onpointertap`	FederatedEventHandler \| null	Handler for 'pointertap' event
`onpointerup`	FederatedEventHandler \| null	Handler for 'pointerup' event
`onpointerupoutside`	FederatedEventHandler \| null	Handler for 'pointerupoutside' event
`onrightclick`	FederatedEventHandler \| null	Handler for 'rightclick' event
`onrightdown`	FederatedEventHandler \| null	Handler for 'rightdown' event
`onrightup`	FederatedEventHandler \| null	Handler for 'rightup' event
`onrightupoutside`	FederatedEventHandler \| null	Handler for 'rightupoutside' event
`ontap`	FederatedEventHandler \| null	Handler for 'tap' event
`ontouchcancel`	FederatedEventHandler \| null	Handler for 'touchcancel' event
`ontouchend`	FederatedEventHandler \| null	Handler for 'touchend' event
`ontouchendoutside`	FederatedEventHandler \| null	Handler for 'touchendoutside' event
`ontouchmove`	FederatedEventHandler \| null	Handler for 'touchmove' event
`ontouchstart`	FederatedEventHandler \| null	Handler for 'touchstart' event
`onwheel`	FederatedEventHandler<FederatedWheelEvent> \| null	Handler for 'wheel' event

IHitArea

The hit area specifies the area for which pointer events should be captured by this event target.

PixiTouch

A PixiJS compatible Touch event.

Type Definitions

Cursor

ts:10

The type of cursor to use when the mouse pointer is hovering over.

Can be any valid CSS cursor value: auto, default, none, context-menu, help, pointer, progress, wait, cell, crosshair, text, verticaltext, alias, copy, move, nodrop, notallowed, eresize, nresize, neresize, nwresize, sresize, seresize, swresize, wresize, nsresize, ewresize, neswresize, colresize, nwseresize, rowresize, allscroll, zoomin, zoomout, grab, grabbing

See:

https://developer.mozilla.org/en-US/docs/Web/CSS/cursor

EventMode

ts:78

The type of interaction a Container can be. This is the eventMode property of any Container.

Can be one of the following:

'none': Ignores all interaction events, even on its children.
'passive': (default) Does not emit events and ignores all hit testing on itself and non-interactive children. Interactive children will still emit events.
'auto': Does not emit events 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
'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

none and passive are useful for optimizing interaction events on objects as it reduces the number of hit tests PixiJS has to do. auto is useful for when you want to recreate how the DOM handles interaction events with pointer-events: auto.

Since:

7.2.0

FederatedEventHandler

ts:72

Function type for handlers, e.g., onclick

TrackingData

ts:3

The tracking data for each pointer held in the state of an EventBoundary.

pressTargetsByButton: {
    [id: number]: Container[];
};
clicksByButton: {
    [id: number]: {
        clickCount: number;
        target: Container;
        timeStamp: number;
    };
};
overTargets: Container[];

Properties:

Name	Type	Description
`clicksByButton`	Record<number, object>	Holds clicking data for each button of the pointer.
`overTargets`	Array<Container>	The Container propagation path over which the pointer is hovering.
`pressTargetsByButton`	Record<Container, number>	The pressed containers' propagation paths by each button of the pointer.