How to Detect Cursor Hover on Pixi.js DisplayObject

Detecting when a user’s cursor is hovering over a specific DisplayObject in Pixi.js is a fundamental requirement for creating interactive games and applications. This article explains how to achieve this using Pixi.js’s built-in event system, covering both the event-driven approach and a programmatic method to check the hover state at any given frame.

The most efficient way to detect a cursor hover is by enabling interactivity on the DisplayObject and listening to pointer events. Pixi.js provides pointerover and pointerout events for this exact purpose.

1. Enable Interactivity

By default, Pixi.js objects do not listen for input events to optimize performance. You must explicitly enable interactivity. * For Pixi.js v7 and newer, set eventMode to 'static' or 'dynamic'. * For Pixi.js v6 and older, set interactive to true.

2. Attach Event Listeners

Listen for pointerover (triggered when the cursor enters the object’s bounds) and pointerout (triggered when the cursor leaves).

import * as PIXI from 'pixi.js';

// Create a DisplayObject (e.g., a Sprite)
const sprite = PIXI.Sprite.from('path/to/image.png');

// Enable interactivity
sprite.eventMode = 'static'; // Use sprite.interactive = true in v6 and below
sprite.cursor = 'pointer';   // Optional: Changes the cursor icon to a hand on hover

// State variable to track hover status
let isHovered = false;

// Event: Cursor enters the object
sprite.on('pointerover', (event) => {
    isHovered = true;
    sprite.alpha = 0.8; // Visual feedback
    console.log('Cursor is hovering');
});

// Event: Cursor leaves the object
sprite.on('pointerout', (event) => {
    isHovered = false;
    sprite.alpha = 1.0; // Reset visual feedback
    console.log('Cursor stopped hovering');
});

Method 2: Programmatic Hit Testing (Real-Time Checking)

If you need to instantly check if the cursor is hovering over a DisplayObject during a specific frame (for example, inside a game loop ticker) without relying purely on event callbacks, you can perform manual hit testing.

You can use the containsPoint method of the DisplayObject combined with the global cursor position provided by the renderer’s event system.

// Assuming 'app' is your PIXI.Application instance and 'sprite' is your DisplayObject
app.ticker.add(() => {
    // 1. Get the current global pointer position
    const globalPosition = app.renderer.events.pointer.global;

    // 2. Check if the pointer position is within the bounds of the DisplayObject
    const isHovering = sprite.containsPoint(globalPosition);

    if (isHovering) {
        // Code to execute when the cursor is currently over the object
        console.log('Cursor is currently over the object');
    }
});

Important Considerations