pixi.js
    Preparing search index...

    Interface FederatedOptions

    The properties available for any interactive object. This interface defines the core interaction properties and event handlers that can be set on any Container in PixiJS.

    // Basic interactive setup
    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';
    sprite.cursor = 'pointer';

    // Using event handlers
    sprite.on('click', (event) => console.log('Sprite clicked!', event));
    sprite.on('pointerdown', (event) => console.log('Pointer down!', event));

    // Using property-based event handlers
    sprite.onclick = (event) => console.log('Clicked!');
    sprite.onpointerenter = () => sprite.alpha = 0.7;
    sprite.onpointerleave = () => sprite.alpha = 1.0;

    // Custom hit area
    sprite.hitArea = new Rectangle(0, 0, 100, 100);

    Core Properties:

    • eventMode: Controls how the object handles interaction events
    • cursor: Sets the mouse cursor when hovering
    • hitArea: Defines custom hit testing area
    • interactive: Alias for eventMode to enable interaction with "static" or "passive" modes
    • interactiveChildren: Controls hit testing on children

    Event Handlers:

    • Mouse: click, mousedown, mouseup, mousemove, mouseenter, mouseleave
    • Touch: touchstart, touchend, touchmove, tap
    • Pointer: pointerdown, pointerup, pointermove, pointerover
    • Global: globalpointermove, globalmousemove, globaltouchmove
    Important

    Global events are fired when the pointer moves even if it is outside the bounds of the Container.

    interface FederatedOptions {
        cursor?: string & {} | Cursor;
        eventMode?: EventMode;
        hitArea?: IHitArea;
        interactive?: boolean;
        interactiveChildren?: boolean;
        onclick?: FederatedEventHandler<FederatedPointerEvent>;
        onglobalmousemove?: FederatedEventHandler<FederatedPointerEvent>;
        onglobalpointermove?: FederatedEventHandler<FederatedPointerEvent>;
        onglobaltouchmove?: FederatedEventHandler<FederatedPointerEvent>;
        onmousedown?: FederatedEventHandler<FederatedPointerEvent>;
        onmouseenter?: FederatedEventHandler<FederatedPointerEvent>;
        onmouseleave?: FederatedEventHandler<FederatedPointerEvent>;
        onmousemove?: FederatedEventHandler<FederatedPointerEvent>;
        onmouseout?: FederatedEventHandler<FederatedPointerEvent>;
        onmouseover?: FederatedEventHandler<FederatedPointerEvent>;
        onmouseup?: FederatedEventHandler<FederatedPointerEvent>;
        onmouseupoutside?: FederatedEventHandler<FederatedPointerEvent>;
        onpointercancel?: FederatedEventHandler<FederatedPointerEvent>;
        onpointerdown?: FederatedEventHandler<FederatedPointerEvent>;
        onpointerenter?: FederatedEventHandler<FederatedPointerEvent>;
        onpointerleave?: FederatedEventHandler<FederatedPointerEvent>;
        onpointermove?: FederatedEventHandler<FederatedPointerEvent>;
        onpointerout?: FederatedEventHandler<FederatedPointerEvent>;
        onpointerover?: FederatedEventHandler<FederatedPointerEvent>;
        onpointertap?: FederatedEventHandler<FederatedPointerEvent>;
        onpointerup?: FederatedEventHandler<FederatedPointerEvent>;
        onpointerupoutside?: FederatedEventHandler<FederatedPointerEvent>;
        onrightclick?: FederatedEventHandler<FederatedPointerEvent>;
        onrightdown?: FederatedEventHandler<FederatedPointerEvent>;
        onrightup?: FederatedEventHandler<FederatedPointerEvent>;
        onrightupoutside?: FederatedEventHandler<FederatedPointerEvent>;
        ontap?: FederatedEventHandler<FederatedPointerEvent>;
        ontouchcancel?: FederatedEventHandler<FederatedPointerEvent>;
        ontouchend?: FederatedEventHandler<FederatedPointerEvent>;
        ontouchendoutside?: FederatedEventHandler<FederatedPointerEvent>;
        ontouchmove?: FederatedEventHandler<FederatedPointerEvent>;
        ontouchstart?: FederatedEventHandler<FederatedPointerEvent>;
        onwheel?: FederatedEventHandler<FederatedWheelEvent>;
    }

    Hierarchy (View Summary)

    Index

    Properties

    cursor?: string & {} | Cursor

    The cursor style to display when the mouse pointer is hovering over the object. Accepts any valid CSS cursor value or custom cursor URL.

    // Common cursor types
    sprite.cursor = 'pointer'; // Hand cursor for clickable elements
    sprite.cursor = 'grab'; // Grab cursor for draggable elements
    sprite.cursor = 'crosshair'; // Precise cursor for selection
    sprite.cursor = 'not-allowed'; // Indicate disabled state

    // Direction cursors
    sprite.cursor = 'n-resize'; // North resize
    sprite.cursor = 'ew-resize'; // East-west resize
    sprite.cursor = 'nesw-resize'; // Northeast-southwest resize

    // Custom cursor with fallback
    sprite.cursor = 'url("custom.png"), auto';
    sprite.cursor = 'url("cursor.cur") 2 2, pointer'; // With hotspot offset
    undefined
    
    eventMode?: EventMode

    Enable interaction events for the Container. Touch, pointer and mouse events are supported.

    const sprite = new Sprite(texture);

    // Enable standard interaction (like buttons)
    sprite.eventMode = 'static';
    sprite.on('pointerdown', () => console.log('clicked!'));

    // Enable for moving objects
    sprite.eventMode = 'dynamic';
    sprite.on('pointermove', () => updatePosition());

    // Disable all interaction
    sprite.eventMode = 'none';

    // Only allow child interactions
    sprite.eventMode = 'passive';

    Available modes:

    • 'none': Ignores all interaction events, even on its children. Best for pure visuals.
    • 'passive': (default) Does not emit events and ignores 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 interactive = true in v7. Best for buttons/UI.
    • 'dynamic': Like static but also receives synthetic events when pointer is idle. Best for moving objects.

    Performance tips:

    • Use 'none' for pure visual elements
    • Use 'passive' for containers with some interactive children
    • Use 'static' for standard UI elements
    • Use 'dynamic' only when needed for moving/animated elements

    7.2.0

    hitArea?: IHitArea

    Defines a custom hit area for pointer interaction testing. When set, this shape will be used for hit testing instead of the container's standard bounds.

    import { Rectangle, Circle, Sprite } from 'pixi.js';

    // Rectangular hit area
    const button = new Sprite(texture);
    button.eventMode = 'static';
    button.hitArea = new Rectangle(0, 0, 100, 50);

    // Circular hit area
    const icon = new Sprite(texture);
    icon.eventMode = 'static';
    icon.hitArea = new Circle(32, 32, 32);

    // Custom hit area with polygon
    const custom = new Sprite(texture);
    custom.eventMode = 'static';
    custom.hitArea = new Polygon([0,0, 100,0, 100,100, 0,100]);

    // Custom hit testing logic
    sprite.hitArea = {
    contains(x: number, y: number) {
    // Custom collision detection
    return x >= 0 && x <= width && y >= 0 && y <= height;
    }
    };
    • Takes precedence over the container's bounds for hit testing
    • Can improve performance by simplifying collision checks
    • Useful for irregular shapes or precise click areas
    interactive?: boolean

    Whether this object should fire UI events. This is an alias for eventMode set to 'static' or 'passive'. Setting this to true will enable interaction events like pointerdown, click, etc. Setting it to false will disable all interaction events on this object.

    // Enable interaction events
    sprite.interactive = true; // Sets eventMode = 'static'
    sprite.interactive = false; // Sets eventMode = 'passive'
    interactiveChildren?: boolean

    Controls whether children of this container can receive pointer events.

    Setting this to false allows PixiJS to skip hit testing on all children, improving performance for containers with many non-interactive children.

    true
    
    // Container with many visual-only children
    const container = new Container();
    container.interactiveChildren = false; // Skip hit testing children

    // Menu with interactive buttons
    const menu = new Container();
    menu.interactiveChildren = true; // Test all children
    menu.addChild(button1, button2, button3);

    // Performance optimization
    background.interactiveChildren = false;
    foreground.interactiveChildren = true;

    Property-based event handler for the click event. Fired when a pointer device (mouse, touch, etc.) completes a click action.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('click', (event) => {
    console.log('Sprite clicked at:', event.global.x, event.global.y);
    });
    // Using property-based handler
    sprite.onclick = (event) => {
    console.log('Clicked at:', event.global.x, event.global.y);
    };
    null
    

    Property-based event handler for the globalmousemove event.

    Fired when the mouse moves anywhere, regardless of whether the pointer is over this object. The object must have eventMode set to 'static' or 'dynamic' to receive this event.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('globalmousemove', (event) => {
    // Move sprite to mouse position
    sprite.position.copyFrom(event.global);
    });
    // Using property-based handler
    sprite.onglobalmousemove = (event) => {
    // Move sprite to mouse position
    sprite.position.copyFrom(event.global);
    };
    null
    
    • Fires even when the mouse is outside the object's bounds
    • Useful for drag operations or global mouse tracking
    • Must have eventMode set appropriately to receive events
    • Part of the global move events family along with globalpointermove and globaltouchmove

    Property-based event handler for the globalpointermove event.

    Fired when the pointer moves anywhere, regardless of whether the pointer is over this object. The object must have eventMode set to 'static' or 'dynamic' to receive this event.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('globalpointermove', (event) => {
    sprite.position.set(event.global.x, event.global.y);
    });
    // Using property-based handler
    sprite.onglobalpointermove = (event) => {
    sprite.position.set(event.global.x, event.global.y);
    };
    null
    
    • Fires even when the mouse is outside the object's bounds
    • Useful for drag operations or global mouse tracking
    • Must have eventMode set appropriately to receive events
    • Part of the global move events family along with globalpointermove and globaltouchmove

    Property-based event handler for the globaltouchmove event.

    Fired when a touch interaction moves anywhere, regardless of whether the pointer is over this object. The object must have eventMode set to 'static' or 'dynamic' to receive this event.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('globaltouchmove', (event) => {
    sprite.position.set(event.global.x, event.global.y);
    });
    // Using property-based handler
    sprite.onglobaltouchmove = (event) => {
    sprite.position.set(event.global.x, event.global.y);
    };
    null
    
    • Fires even when the touch is outside the object's bounds
    • Useful for drag operations or global touch tracking
    • Must have eventMode set appropriately to receive events
    • Part of the global move events family along with globalpointermove and globalmousemove

    Property-based event handler for the mousedown event. Fired when a mouse button is pressed while the pointer is over the object.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('mousedown', (event) => {
    sprite.alpha = 0.5; // Visual feedback
    console.log('Mouse button:', event.button);
    });
    // Using property-based handler
    sprite.onmousedown = (event) => {
    sprite.alpha = 0.5; // Visual feedback
    console.log('Mouse button:', event.button);
    };
    null
    

    Property-based event handler for the mouseenter event. Fired when the mouse pointer enters the bounds of the object. Does not bubble.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('mouseenter', (event) => {
    sprite.scale.set(1.1);
    });
    // Using property-based handler
    sprite.onmouseenter = (event) => {
    sprite.scale.set(1.1);
    };
    null
    

    Property-based event handler for the mouseleave event. Fired when the pointer leaves the bounds of the display object. Does not bubble.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('mouseleave', (event) => {
    sprite.scale.set(1.0);
    });
    // Using property-based handler
    sprite.onmouseleave = (event) => {
    sprite.scale.set(1.0);
    };
    null
    

    Property-based event handler for the mousemove event. Fired when the pointer moves while over the display object.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('mousemove', (event) => {
    // Get coordinates relative to the sprite
    console.log('Local:', event.getLocalPosition(sprite));
    });
    // Using property-based handler
    sprite.onmousemove = (event) => {
    // Get coordinates relative to the sprite
    console.log('Local:', event.getLocalPosition(sprite));
    };
    null
    

    Property-based event handler for the mouseout event. Fired when the pointer moves out of the bounds of the display object.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('mouseout', (event) => {
    sprite.scale.set(1.0);
    });
    // Using property-based handler
    sprite.onmouseout = (event) => {
    sprite.scale.set(1.0);
    };
    null
    

    Property-based event handler for the mouseover event. Fired when the pointer moves onto the bounds of the display object.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('mouseover', (event) => {
    sprite.scale.set(1.1);
    });
    // Using property-based handler
    sprite.onmouseover = (event) => {
    sprite.scale.set(1.1);
    };
    null
    

    Property-based event handler for the mouseup event. Fired when a mouse button is released over the display object.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('mouseup', (event) => {
    sprite.scale.set(1.0);
    });
    // Using property-based handler
    sprite.onmouseup = (event) => {
    sprite.scale.set(1.0);
    };
    null
    

    Property-based event handler for the mouseupoutside event. Fired when a mouse button is released outside the display object that initially registered a mousedown.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('mouseupoutside', (event) => {
    sprite.scale.set(1.0);
    });
    // Using property-based handler
    sprite.onmouseupoutside = (event) => {
    sprite.scale.set(1.0);
    };
    null
    

    Property-based event handler for the pointercancel event. Fired when a pointer device interaction is canceled or lost.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('pointercancel', (event) => {
    sprite.scale.set(1.0);
    });
    // Using property-based handler
    sprite.onpointercancel = (event) => {
    sprite.scale.set(1.0);
    };
    null
    

    Property-based event handler for the pointerdown event. Fired when a pointer device button (mouse, touch, pen, etc.) is pressed.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('pointerdown', (event) => {
    sprite.position.set(event.global.x, event.global.y);
    });
    // Using property-based handler
    sprite.onpointerdown = (event) => {
    sprite.position.set(event.global.x, event.global.y);
    };
    null
    

    Property-based event handler for the pointerenter event. Fired when a pointer device enters the bounds of the display object. Does not bubble.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('pointerenter', (event) => {
    sprite.scale.set(1.2);
    });
    // Using property-based handler
    sprite.onpointerenter = (event) => {
    sprite.scale.set(1.2);
    };
    null
    

    Property-based event handler for the pointerleave event. Fired when a pointer device leaves the bounds of the display object. Does not bubble.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';
    // Using emitter handler
    sprite.on('pointerleave', (event) => {
    sprite.scale.set(1.0);
    });
    // Using property-based handler
    sprite.onpointerleave = (event) => {
    sprite.scale.set(1.0);
    };
    null
    

    Property-based event handler for the pointermove event. Fired when a pointer device moves while over the display object.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('pointermove', (event) => {
    sprite.position.set(event.global.x, event.global.y);
    });
    // Using property-based handler
    sprite.onpointermove = (event) => {
    sprite.position.set(event.global.x, event.global.y);
    };
    null
    

    Property-based event handler for the pointerout event. Fired when the pointer moves out of the bounds of the display object.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('pointerout', (event) => {
    sprite.scale.set(1.0);
    });
    // Using property-based handler
    sprite.onpointerout = (event) => {
    sprite.scale.set(1.0);
    };
    null
    

    Property-based event handler for the pointerover event. Fired when the pointer moves over the bounds of the display object.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('pointerover', (event) => {
    sprite.scale.set(1.2);
    });
    // Using property-based handler
    sprite.onpointerover = (event) => {
    sprite.scale.set(1.2);
    };
    null
    

    Property-based event handler for the pointertap event. Fired when a pointer device completes a tap action (e.g., touch or mouse click).

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('pointertap', (event) => {
    console.log('Sprite tapped at:', event.global.x, event.global.y);
    });
    // Using property-based handler
    sprite.onpointertap = (event) => {
    console.log('Sprite tapped at:', event.global.x, event.global.y);
    };
    null
    

    Property-based event handler for the pointerup event. Fired when a pointer device button (mouse, touch, pen, etc.) is released.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('pointerup', (event) => {
    sprite.scale.set(1.0);
    });
    // Using property-based handler
    sprite.onpointerup = (event) => {
    sprite.scale.set(1.0);
    };
    null
    

    Property-based event handler for the pointerupoutside event. Fired when a pointer device button is released outside the bounds of the display object that initially registered a pointerdown.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('pointerupoutside', (event) => {
    sprite.scale.set(1.0);
    });
    // Using property-based handler
    sprite.onpointerupoutside = (event) => {
    sprite.scale.set(1.0);
    };
    null
    

    Property-based event handler for the rightclick event. Fired when a right-click (context menu) action is performed on the object.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('rightclick', (event) => {
    console.log('Right-clicked at:', event.global.x, event.global.y);
    });
    // Using property-based handler
    sprite.onrightclick = (event) => {
    console.log('Right-clicked at:', event.global.x, event.global.y);
    };
    null
    

    Property-based event handler for the rightdown event. Fired when a right mouse button is pressed down over the display object.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('rightdown', (event) => {
    sprite.scale.set(0.9);
    });
    // Using property-based handler
    sprite.onrightdown = (event) => {
    sprite.scale.set(0.9);
    };
    null
    

    Property-based event handler for the rightup event. Fired when a right mouse button is released over the display object.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('rightup', (event) => {
    sprite.scale.set(1.0);
    });
    // Using property-based handler
    sprite.onrightup = (event) => {
    sprite.scale.set(1.0);
    };
    null
    

    Property-based event handler for the rightupoutside event. Fired when a right mouse button is released outside the bounds of the display object that initially registered a rightdown.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('rightupoutside', (event) => {
    sprite.scale.set(1.0);
    });
    // Using property-based handler
    sprite.onrightupoutside = (event) => {
    sprite.scale.set(1.0);
    };
    null
    

    Property-based event handler for the tap event. Fired when a tap action (touch) is completed on the object.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('tap', (event) => {
    console.log('Sprite tapped at:', event.global.x, event.global.y);
    });
    // Using property-based handler
    sprite.ontap = (event) => {
    console.log('Sprite tapped at:', event.global.x, event.global.y);
    };
    null
    

    Property-based event handler for the touchcancel event. Fired when a touch interaction is canceled, such as when the touch is interrupted.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('touchcancel', (event) => {
    console.log('Touch canceled at:', event.global.x, event.global.y);
    });
    // Using property-based handler
    sprite.ontouchcancel = (event) => {
    console.log('Touch canceled at:', event.global.x, event.global.y);
    };
    null
    

    Property-based event handler for the touchend event. Fired when a touch interaction ends, such as when the finger is lifted from the screen.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('touchend', (event) => {
    sprite.scale.set(1.0);
    });
    // Using property-based handler
    sprite.ontouchend = (event) => {
    sprite.scale.set(1.0);
    };
    null
    

    Property-based event handler for the touchendoutside event. Fired when a touch interaction ends outside the bounds of the display object that initially registered a touchstart.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('touchendoutside', (event) => {
    sprite.scale.set(1.0);
    });
    // Using property-based handler
    sprite.ontouchendoutside = (event) => {
    sprite.scale.set(1.0);
    };
    null
    

    Property-based event handler for the touchmove event. Fired when a touch interaction moves while over the display object.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('touchmove', (event) => {
    sprite.position.set(event.global.x, event.global.y);
    });
    // Using property-based handler
    sprite.ontouchmove = (event) => {
    sprite.position.set(event.global.x, event.global.y);
    };
    null
    

    Property-based event handler for the touchstart event. Fired when a touch interaction starts, such as when a finger touches the screen.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('touchstart', (event) => {
    sprite.scale.set(0.9);
    });
    // Using property-based handler
    sprite.ontouchstart = (event) => {
    sprite.scale.set(0.9);
    };
    null
    

    Property-based event handler for the wheel event. Fired when the mouse wheel is scrolled while over the display object.

    const sprite = new Sprite(texture);
    sprite.eventMode = 'static';

    // Using emitter handler
    sprite.on('wheel', (event) => {
    sprite.scale.x += event.deltaY * 0.01; // Zoom in/out
    sprite.scale.y += event.deltaY * 0.01; // Zoom in/out
    });
    // Using property-based handler
    sprite.onwheel = (event) => {
    sprite.scale.x += event.deltaY * 0.01; // Zoom in/out
    sprite.scale.y += event.deltaY * 0.01; // Zoom in/out
    };
    null