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.

Event Modes

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.

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

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 twice 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 twice 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 Container-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 = Sprite.from('/some/texture.png');
sprite.on('pointerdown', (event) => { alert('clicked!'); });
sprite.eventMode = 'static';

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

Classes

EventBoundary
EventsTickerClass
EventSystem
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

Describes the shape for a FederatedEvent's' eventTarget.

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 options for interactive objects.

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

PixiTouch

A PixiJS compatible Touch event.

Members

EventsTicker EventsTickerClass readonly

This class handles automatic firing of PointerEvents in the case where the pointer is stationary for too long. This is to ensure that hit-tests are still run on moving objects.

Since:
  • 7.2.0

Type Definitions

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:

The type of interaction a Container can be. For more information on values and their meaning, see Container's eventMode property.

Can be one of the following:

  • 'none': Ignores all interaction events, even on its children.
  • 'passive': 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

Function type for handlers, e.g., onclick

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

pressTargetsByButton: {
    [id: number]: FederatedEventTarget[];
};
clicksByButton: {
    [id: number]: {
        clickCount: number;
        target: FederatedEventTarget;
        timeStamp: number;
    };
};
overTargets: FederatedEventTarget[];
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<FederatedEventTarget, number>

The pressed containers' propagation paths by each button of the pointer.