OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add pixijs/pixijs-skills --skill pixijs-events
Use this skill when handling pointer, mouse, touch, or wheel input in PixiJS v8. Covers eventMode (none, passive, auto, static, dynamic), FederatedEvent types, propagation and capture phase, hitArea, interactiveChildren, cursor and cursorStyles, global move events for drag, eventFeatures config. Triggers on: eventMode, FederatedPointerEvent, pointerdown, click, tap, globalpointermove, drag, hitArea, cursor, stopPropagation.
npx skills add pixijs/pixijs-skills --skill pixijs-events
PixiJS's federated event system mirrors DOM events on the scene graph. Set container.eventMode = 'static' to opt an object in, then listen with .on(), addEventListener(), or onEventName property handlers. Move events fire only over the listening object; use globalpointermove for drag.
Related skills: pixijs-accessibility (screen reader + keyboard), pixijs-scene-dom-container (HTML overlays), pixijs-performance (event-heavy scenes).
Use 'static' for buttons, UI elements, and drag targets. Use 'dynamic' only for objects that move under a stationary cursor and need continuous hover updates.
Use isInteractive() to check whether an object can receive events:
Pointer events (recommended for cross-device compatibility): pointerdown, pointerup, pointerupoutside, pointermove, pointerover, pointerout, pointerenter, pointerleave, pointertap, pointercancel.
Mouse events: mousedown, mouseup, mouseupoutside, mousemove, mouseover, mouseout, mouseenter, mouseleave, click, rightdown, rightup, rightupoutside, rightclick, wheel.
Touch events: touchstart, touchend, touchendoutside, touchmove, touchcancel, tap. Each touch carries altKey, ctrlKey, metaKey, and shiftKey copied from the native TouchEvent, so modifier keys work the same as with mouse or pointer events.
Global move events: globalpointermove, globalmousemove, globaltouchmove. These fire on every pointer movement regardless of whether the pointer is over the listening object.
Container lifecycle events (no eventMode required): added, removed, destroyed, childAdded, childRemoved, visibleChanged.
All events support capture phase by appending capture to the event name (e.g., pointerdowncapture, clickcapture). Capture listeners fire during the capturing phase, before the event reaches its target.
When a pointer event fires, PixiJS walks the display tree to find the top-most interactive element under the pointer. The traversal follows these rules:
eventMode = 'none' on a container skips that element and its entire subtree.interactiveChildren = false on a container skips its children (the container itself can still be tested).hitArea overrides bounds-based testing; only the shape is checked.Set a custom hitArea to override bounds-based testing. This also speeds up hit tests on large or complex objects by reducing the geometry checked:
Basic usage sets the cursor property per-object. For reusable cursors, register named styles on the event system:
Cursor styles can be strings (CSS cursor values), objects (applied as CSS styles), or functions (called with the mode string).
FederatedPointerEvent carries rich input data; the more useful fields are:
FederatedWheelEvent adds deltaX, deltaY, deltaZ, and deltaMode. Wheel events fire on the same hit-tested object as pointer events.
Toggle event categories globally for performance:
eventMode = 'none' on non-interactive subtrees to skip hit testing entirely.interactiveChildren = false on containers where only the container itself needs interaction.hitArea on large or complex objects to replace bounds-based hit testing with a cheap shape check.'static' for stationary elements; reserve 'dynamic' for objects that move or animate under a stationary pointer.eventFeatures (e.g., globalMove: false) to cut per-frame work.Wrong:
Correct:
The default eventMode is 'passive', which means the object itself receives no events. You must explicitly set eventMode to 'static' or 'dynamic' before any listener will fire.
Wrong:
Correct:
buttonMode was removed in v8. Use cursor = 'pointer' to show a hand cursor on hover. interactive = true still works as an alias for eventMode = 'static', but eventMode is preferred.
Wrong:
Correct:
In v8, pointermove, mousemove, and touchmove only fire when the pointer is over the display object. In v7 they fired on any canvas move. For drag operations or global tracking, use globalpointermove, globalmousemove, or globaltouchmove.
Setting cursor on a parent container has no effect on its children. Only the direct hit target's cursor value is applied.
If you want a uniform cursor for all children, set cursor on each interactive child individually, or set hitArea on the parent and make children non-interactive.
import { Sprite } from "pixi.js";
const sprite = new Sprite();
// No interaction at all; children also ignored
sprite.eventMode = "none";
// Default. Self not interactive; interactive children still work
sprite.eventMode = "passive";
// Hit tested only when a parent is interactive
sprite.eventMode = "auto";
// Standard interaction: receives pointer/mouse/touch events
sprite.eventMode = "static";
// Like static, but also fires synthetic events from the ticker
// when the pointer is stationary (for animated objects under cursor)
sprite.eventMode = "dynamic";sprite.eventMode = "static";
sprite.isInteractive(); // true
sprite.eventMode = "passive";
sprite.isInteractive(); // falseimport { Sprite } from "pixi.js";
const sprite = new Sprite();
sprite.eventMode = "static";
// EventEmitter style (recommended)
const handler = (e) => console.log("clicked");
sprite.on("pointerdown", handler);
sprite.once("pointerdown", handler); // one-time
sprite.off("pointerdown", handler);
// DOM style
sprite.addEventListener(
"click",
(event) => {
console.log("Clicked!", event.detail);
},
{ once: true },
);
// Property-based handlers
sprite.onclick = (event) => {
console.log("Clicked!", event.detail);
};import { Sprite, Container } from "pixi.js";
const parent = new Container();
parent.eventMode = "static";
const child = new Sprite();
child.eventMode = "static";
parent.addChild(child);
child.on("pointerdown", (event) => {
console.log("child pressed");
event.stopPropagation(); // prevent parent from receiving this event
});
parent.on("pointerdown", () => {
console.log("parent pressed (only if child did not stop propagation)");
});container.addEventListener(
"pointerdown",
(event) => {
event.stopImmediatePropagation(); // blocks event from reaching children
},
{ capture: true },
);import { Sprite, Rectangle, Circle, Polygon } from "pixi.js";
const sprite = new Sprite();
sprite.eventMode = "static";
// Rectangular hit area
sprite.hitArea = new Rectangle(0, 0, 100, 50);
// Circular hit area
sprite.hitArea = new Circle(50, 50, 40);
// Polygon hit area
sprite.hitArea = new Polygon([0, 0, 100, 0, 50, 100]);
// Custom hit test via contains()
sprite.hitArea = {
contains(x: number, y: number): boolean {
return x >= 0 && x <= 100 && y >= 0 && y <= 100;
},
};import { Sprite, FederatedPointerEvent } from "pixi.js";
const sprite = new Sprite();
sprite.eventMode = "static";
sprite.cursor = "grab";
let dragging = false;
sprite.on("pointerdown", (event: FederatedPointerEvent) => {
dragging = true;
sprite.cursor = "grabbing";
});
// globalpointermove fires even when pointer leaves the object
sprite.on("globalpointermove", (event: FederatedPointerEvent) => {
if (dragging) {
sprite.position.set(event.global.x, event.global.y);
}
});
sprite.on("pointerup", () => {
dragging = false;
sprite.cursor = "grab";
});
sprite.on("pointerupoutside", () => {
dragging = false;
sprite.cursor = "grab";
});app.renderer.events.cursorStyles.default = "url('bunny.png'), auto";
app.renderer.events.cursorStyles.hover = "url('bunny_saturated.png'), auto";
sprite.eventMode = "static";
sprite.cursor = "hover"; // uses the registered 'hover' stylesprite.on("pointerdown", (event: FederatedPointerEvent) => {
event.global; // scene-space Point where the event happened
event.client; // CSS-pixel Point relative to the viewport
event.offset; // Point w.r.t. target Container in world space (not supported at the moment)
event.target; // the Container that received the event
event.currentTarget; // the Container whose listener is running
event.pointerType; // 'mouse' | 'pen' | 'touch'
event.pointerId; // unique id for multi-touch tracking
event.isPrimary; // first pointer in a multi-pointer gesture
event.pressure; // 0-1 pen/touch pressure
event.button; // 0 left, 1 middle, 2 right
event.buttons; // bitmask of held buttons
event.altKey; // modifier key state
event.ctrlKey;
event.shiftKey;
event.metaKey;
event.nativeEvent; // the underlying DOM PointerEvent / MouseEvent / Touch
event.preventDefault();
event.stopPropagation();
event.stopImmediatePropagation();
});await app.init({
eventFeatures: {
move: true, // pointer/mouse/touch move events
globalMove: true, // global move events (globalpointermove, etc.)
click: true, // click/tap/press events
wheel: true, // mouse wheel events
},
});
// or configure after init
app.renderer.events.features.globalMove = false;const sprite = new Sprite(texture);
sprite.on("pointerdown", () => {
console.log("clicked");
});const sprite = new Sprite(texture);
sprite.eventMode = "static";
sprite.on("pointerdown", () => {
console.log("clicked");
});sprite.interactive = true;
sprite.buttonMode = true;sprite.eventMode = "static";
sprite.cursor = "pointer";sprite.eventMode = "static";
sprite.on("pointermove", (event) => {
// expects to fire everywhere; only fires inside sprite bounds
updateDrag(event.global.x, event.global.y);
});sprite.eventMode = "static";
sprite.on("globalpointermove", (event) => {
// fires everywhere, even outside sprite bounds
updateDrag(event.global.x, event.global.y);
});// This does NOT make children show a pointer cursor
parent.cursor = "pointer";
// Each interactive child needs its own cursor
child.eventMode = "static";
child.cursor = "pointer";