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 events.Cursor | string

The cursor preferred when the mouse pointer is hovering over.

eventMode events.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 events.FederatedEventHandler | null

Handler for 'click' event

onglobalmousemove events.FederatedEventHandler | null

Handler for 'globalmousemove' event

onglobalpointermove events.FederatedEventHandler | null

Handler for 'globalpointermove' event

onglobaltouchmove events.FederatedEventHandler | null

Handler for 'globaltouchmove' event

onmousedown events.FederatedEventHandler | null

Handler for 'mousedown' event

onmouseenter events.FederatedEventHandler | null

Handler for 'mouseenter' event

onmouseleave events.FederatedEventHandler | null

Handler for 'mouseleave' event

onmousemove events.FederatedEventHandler | null

Handler for 'mousemove' event

onmouseout events.FederatedEventHandler | null

Handler for 'mouseout' event

onmouseover events.FederatedEventHandler | null

Handler for 'mouseover' event

onmouseup events.FederatedEventHandler | null

Handler for 'mouseup' event

onmouseupoutside events.FederatedEventHandler | null

Handler for 'mouseupoutside' event

onpointercancel events.FederatedEventHandler | null

Handler for 'pointercancel' event

onpointerdown events.FederatedEventHandler | null

Handler for 'pointerdown' event

onpointerenter events.FederatedEventHandler | null

Handler for 'pointerenter' event

onpointerleave events.FederatedEventHandler | null

Handler for 'pointerleave' event

onpointermove events.FederatedEventHandler | null

Handler for 'pointermove' event

onpointerout events.FederatedEventHandler | null

Handler for 'pointerout' event

onpointerover events.FederatedEventHandler | null

Handler for 'pointerover' event

onpointertap events.FederatedEventHandler | null

Handler for 'pointertap' event

onpointerup events.FederatedEventHandler | null

Handler for 'pointerup' event

onpointerupoutside events.FederatedEventHandler | null

Handler for 'pointerupoutside' event

onrightclick events.FederatedEventHandler | null

Handler for 'rightclick' event

onrightdown events.FederatedEventHandler | null

Handler for 'rightdown' event

onrightup events.FederatedEventHandler | null

Handler for 'rightup' event

onrightupoutside events.FederatedEventHandler | null

Handler for 'rightupoutside' event

ontap events.FederatedEventHandler | null

Handler for 'tap' event

ontouchcancel events.FederatedEventHandler | null

Handler for 'touchcancel' event

ontouchend events.FederatedEventHandler | null

Handler for 'touchend' event

ontouchendoutside events.FederatedEventHandler | null

Handler for 'touchendoutside' event

ontouchmove events.FederatedEventHandler | null

Handler for 'touchmove' event

ontouchstart events.FederatedEventHandler | null

Handler for 'touchstart' event

onwheel events.FederatedEventHandler<events.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.