Defined in: node_modules/pixi.js/lib/events/EventSystem.d.ts:213

The system for handling UI events in PixiJS applications. This class manages mouse, touch, and pointer events, normalizing them into a consistent event model.

Example

// Access event system through renderer
const eventSystem = app.renderer.events;

// Configure event features
eventSystem.features.globalMove = false;  // Disable global move events
eventSystem.features.click = true;        // Enable click events

// Set custom cursor styles
eventSystem.cursorStyles.default = 'pointer';
eventSystem.cursorStyles.grab = 'grab';

// Get current pointer position
const pointer = eventSystem.pointer;
console.log(pointer.global.x, pointer.global.y);

Features:

Normalizes browser events into consistent format
Supports mouse, touch, and pointer events
Handles event delegation and bubbling
Provides cursor management
Configurable event features

See

EventBoundary For event propagation and handling
FederatedEvent For the base event class
EventMode For interaction modes

Standard

Implements

System<EventSystemOptions>

Constructors

Constructor

> new EventSystem(renderer): EventSystem

Defined in: node_modules/pixi.js/lib/events/EventSystem.d.ts:382

Parameters

renderer

Renderer

Returns

EventSystem

Properties

autoPreventDefault

> autoPreventDefault: boolean

Defined in: node_modules/pixi.js/lib/events/EventSystem.d.ts:296

Controls whether default browser actions are automatically prevented on pointer events. When true, prevents default browser actions from occurring on pointer events.

Remarks

Does not apply to pointer events for backwards compatibility
preventDefault on pointer events stops mouse events from firing
For every pointer event, there will always be either a mouse or touch event alongside it
Setting this to false allows default browser actions (text selection, dragging images, etc.)

Example

// Allow default browser actions
app.renderer.events.autoPreventDefault = false;

// Block default actions (default)
app.renderer.events.autoPreventDefault = true;

// Example with text selection
const text = new Text('Selectable text');
text.eventMode = 'static';
app.renderer.events.autoPreventDefault = false; // Allow text selection

Default

true

cursorStyles

> cursorStyles: Record<string, string | ((mode) => void) | CSSStyleDeclaration>

Defined in: node_modules/pixi.js/lib/events/EventSystem.d.ts:349

Dictionary of custom cursor styles that can be used across the application. Used to define how different cursor modes are handled when interacting with display objects.

Example

// Access event system through renderer
const eventSystem = app.renderer.events;

// Set string-based cursor styles
eventSystem.cursorStyles.default = 'pointer';
eventSystem.cursorStyles.hover = 'grab';
eventSystem.cursorStyles.drag = 'grabbing';

// Use CSS object for complex styling
eventSystem.cursorStyles.custom = {
    cursor: 'url("custom.png") 2 2, auto',
    userSelect: 'none'
};

// Use a url for custom cursors
const defaultIcon = 'url(\'https://pixijs.com/assets/bunny.png\'),auto';
eventSystem.cursorStyles.icon = defaultIcon;

// Use callback function for dynamic cursors
eventSystem.cursorStyles.dynamic = (mode) => {
    // Update cursor based on mode
    document.body.style.cursor = mode === 'hover'
        ? 'pointer'
        : 'default';
};

// Apply cursor style to a sprite
sprite.cursor = 'hover'; // Will use the hover style defined above
sprite.cursor = 'icon'; // Will apply the icon cursor
sprite.cursor = 'custom'; // Will apply the custom CSS styles
sprite.cursor = 'drag'; // Will apply the grabbing cursor
sprite.cursor = 'default'; // Will apply the default pointer cursor
sprite.cursor = 'dynamic'; // Will call the dynamic function

Remarks

Strings are treated as CSS cursor values
Objects are applied as CSS styles to the DOM element
Functions are called directly for custom cursor handling
Default styles for 'default' and 'pointer' are provided

Default

{
    default: 'inherit',
    pointer: 'pointer' // Default cursor styles
}

domElement

> domElement: HTMLElement

Defined in: node_modules/pixi.js/lib/events/EventSystem.d.ts:354

The DOM element to which the root event listeners are bound. This is automatically set to the renderer's Renderer#view view.

features

> readonly features: EventSystemFeatures

Defined in: node_modules/pixi.js/lib/events/EventSystem.d.ts:374

The event features that are enabled by the EventSystem

Since

7.2.0

Example

const app = new Application()
app.renderer.events.features.globalMove = false

// to override all features use Object.assign
Object.assign(app.renderer.events.features, {
 move: false,
 globalMove: false,
 click: false,
 wheel: false,
})

renderer

> renderer: Renderer

Defined in: node_modules/pixi.js/lib/events/EventSystem.d.ts:358

The renderer managing this EventSystem.

resolution

> resolution: number

Defined in: node_modules/pixi.js/lib/events/EventSystem.d.ts:356

The resolution used to convert between the DOM client space into world space.

rootBoundary

> readonly rootBoundary: EventBoundary

Defined in: node_modules/pixi.js/lib/events/EventSystem.d.ts:256

The EventBoundary for the stage.

The rootTarget of this root boundary is automatically set to the last rendered object before any event processing is initiated. This means the main scene needs to be rendered atleast once before UI events will start propagating.

The root boundary should only be changed during initialization. Otherwise, any state held by the event boundary may be lost (like hovered & pressed Containers).

Advanced

supportsPointerEvents

> readonly supportsPointerEvents: boolean

Defined in: node_modules/pixi.js/lib/events/EventSystem.d.ts:272

Indicates whether the current device supports pointer events according to the W3C Pointer Events spec. Used to optimize event handling and provide more consistent cross-device interaction.

See

https://www.w3.org/TR/pointerevents/ W3C Pointer Events Specification

Default

!!globalThis.PointerEvent

supportsTouchEvents

> readonly supportsTouchEvents: boolean

Defined in: node_modules/pixi.js/lib/events/EventSystem.d.ts:264

Indicates whether the current device supports touch events according to the W3C Touch Events spec. This is used to determine the appropriate event handling strategy.

See

https://www.w3.org/TR/touch-events/ W3C Touch Events Specification

Default

'ontouchstart' in globalThis

defaultEventFeatures

> static defaultEventFeatures: EventSystemFeatures

Defined in: node_modules/pixi.js/lib/events/EventSystem.d.ts:235

The event features that are enabled by the EventSystem

Since

7.2.0

Example

import { EventSystem, EventSystemFeatures } from 'pixi.js';
// Access the default event features
EventSystem.defaultEventFeatures = {
    // Enable pointer movement events
    move: true,
    // Enable global pointer move events
    globalMove: true,
    // Enable click events
    click: true,
    // Enable wheel events
    wheel: true,
};

Accessors

pointer

Get Signature

> get pointer(): Readonly<FederatedPointerEvent>

Defined in: node_modules/pixi.js/lib/events/EventSystem.d.ts:450

The global pointer event instance containing the most recent pointer state. This is useful for accessing pointer information without listening to events.

Example

// Access current pointer position at any time
const eventSystem = app.renderer.events;
const pointer = eventSystem.pointer;

// Get global coordinates
console.log('Position:', pointer.global.x, pointer.global.y);

// Check button state
console.log('Buttons pressed:', pointer.buttons);

// Get pointer type and pressure
console.log('Type:', pointer.pointerType);
console.log('Pressure:', pointer.pressure);

Since

7.2.0

See

FederatedPointerEvent For all available pointer properties

Returns

Readonly<FederatedPointerEvent>

defaultEventMode

Get Signature

> get static defaultEventMode(): EventMode

Defined in: node_modules/pixi.js/lib/events/EventSystem.d.ts:244

The default interaction mode for all display objects.

See

Container.eventMode

Since

7.2.0

Returns

EventMode

Methods

destroy()

> destroy(): void

Defined in: node_modules/pixi.js/lib/events/EventSystem.d.ts:394

Destroys all event listeners and detaches the renderer.

Returns

void

Implementation of

System.destroy

mapPositionToPoint()

> mapPositionToPoint(point, x, y): void

Defined in: node_modules/pixi.js/lib/events/EventSystem.d.ts:539

Maps coordinates from DOM/screen space into PixiJS normalized coordinates. This takes into account the current scale, position, and resolution of the DOM element.

Parameters

point

PointData

The point to store the mapped coordinates in

x

number

The x coordinate in DOM/client space

y

number

The y coordinate in DOM/client space

Returns

void

Example

// Map mouse coordinates to PixiJS space
const point = new Point();
app.renderer.events.mapPositionToPoint(
    point,
    event.clientX,
    event.clientY
);
console.log('Mapped position:', point.x, point.y);

// Using with pointer events
sprite.on('pointermove', (event) => {
    // event.global already contains mapped coordinates
    console.log('Global:', event.global.x, event.global.y);

    // Map to local coordinates
    const local = event.getLocalPosition(sprite);
    console.log('Local:', local.x, local.y);
});

Remarks

Accounts for element scaling and positioning
Adjusts for device pixel ratio/resolution

normalizeWheelEvent()

> protected normalizeWheelEvent(nativeEvent): FederatedWheelEvent

Defined in: node_modules/pixi.js/lib/events/EventSystem.d.ts:555

Normalizes the native WheelEvent.

The returned FederatedWheelEvent is a shared instance. It will not persist across multiple native wheel events.

Parameters

nativeEvent

WheelEvent

The native wheel event that occurred on the canvas.

Returns

FederatedWheelEvent

A federated wheel event.

onWheel()

> protected onWheel(nativeEvent): void

Defined in: node_modules/pixi.js/lib/events/EventSystem.d.ts:475

Passive handler for wheel events on this.domElement.

Parameters

nativeEvent

WheelEvent

The native wheel event.

Returns

void

setCursor()

> setCursor(mode): void

Defined in: node_modules/pixi.js/lib/events/EventSystem.d.ts:426

Sets the current cursor mode, handling any callbacks or CSS style changes. The cursor can be a CSS cursor string, a custom callback function, or a key from the cursorStyles dictionary.

Parameters

mode

string

Cursor mode to set. Can be:

A CSS cursor string (e.g., 'pointer', 'grab')
A key from the cursorStyles dictionary
null/undefined to reset to default

Returns

void

Example

// Using predefined cursor styles
app.renderer.events.setCursor('pointer');    // Set standard pointer cursor
app.renderer.events.setCursor('grab');       // Set grab cursor
app.renderer.events.setCursor(null);         // Reset to default

// Using custom cursor styles
app.renderer.events.cursorStyles.custom = 'url("cursor.png"), auto';
app.renderer.events.setCursor('custom');     // Apply custom cursor

// Using callback-based cursor
app.renderer.events.cursorStyles.dynamic = (mode) => {
    document.body.style.cursor = mode === 'hover' ? 'pointer' : 'default';
};
app.renderer.events.setCursor('dynamic');    // Trigger cursor callback

Remarks

Has no effect on OffscreenCanvas except for callback-based cursors
Caches current cursor to avoid unnecessary DOM updates
Supports CSS cursor values, style objects, and callback functions

See

EventSystem.cursorStyles For defining custom cursor styles
https://developer.mozilla.org/en-US/docs/Web/CSS/cursor MDN Cursor Reference

setTargetElement()

> setTargetElement(element): void

Defined in: node_modules/pixi.js/lib/events/EventSystem.d.ts:503

Sets the domElement and binds event listeners. This method manages the DOM event bindings for the event system, allowing you to change or remove the target element that receives input events. > [!IMPORTANT] This will default to the canvas element of the renderer, so you > should not need to call this unless you are using a custom element.

Parameters

element

HTMLElement

The new DOM element to bind events to, or null to remove all event bindings

Returns

void

Example

// Set a new canvas element as the target
const canvas = document.createElement('canvas');
app.renderer.events.setTargetElement(canvas);

// Remove all event bindings
app.renderer.events.setTargetElement(null);

// Switch to a different canvas
const newCanvas = document.querySelector('#game-canvas');
app.renderer.events.setTargetElement(newCanvas);

Remarks

Automatically removes event listeners from previous element
Required for the event system to function
Safe to call multiple times

See

EventSystem#domElement The current DOM element
EventsTicker For the ticker system that tracks pointer movement

Class: EventSystem

Example

See

Standard

Implements

Constructors

Constructor

Parameters

renderer

Returns

Properties

autoPreventDefault

Remarks

Example

Default

cursorStyles

Example

Remarks

Default

domElement

features

Since

Example

renderer

resolution

rootBoundary

Advanced

supportsPointerEvents

See

Default

supportsTouchEvents

See

Default

defaultEventFeatures

Since

Example

Accessors

pointer

Get Signature

Example

Since

See

Returns

defaultEventMode

Get Signature

See

Since

Returns

Methods

destroy()

Returns

Implementation of

mapPositionToPoint()

Parameters

point

x

y

Returns

Example

Remarks

normalizeWheelEvent()

Parameters

nativeEvent

Returns

onWheel()

Parameters

nativeEvent

Returns

setCursor()

Parameters

mode

Returns

Example

Remarks

See

setTargetElement()

Parameters

element

Returns

Example