pixi-viewport

To use the viewport, create a new Viewport instance, providing the screen dimensions, world dimensions, and the PIXI renderer's events. Add the viewport to your PIXI stage and activate desired plugins like drag(), pinch(), wheel(), or decelerate().

import * as PIXI from "pixi.js";
import { Viewport } from "pixi-viewport";

const app = new PIXI.Application();
document.body.appendChild(app.view);

// create viewport
const viewport = new Viewport({
  screenWidth: window.innerWidth,
  screenHeight: window.innerHeight,
  worldWidth: 1000,
  worldHeight: 1000,
  events: app.renderer.events, // the interaction module is important for wheel to work properly when renderer.view is placed or scaled
});

// add the viewport to the stage
app.stage.addChild(viewport);

// activate plugins
viewport.drag().pinch().wheel().decelerate();

// add a red box
const sprite = viewport.addChild(new PIXI.Sprite(PIXI.Texture.WHITE));
sprite.tint = 0xff0000;
sprite.width = sprite.height = 100;
sprite.position.set(100, 100);

When instantiating a Viewport, you can provide an options object of type IViewportOptions to define the initial state of the camera and its interaction behavior.

Key options include:

• screenWidth / screenHeight: The dimensions of the visible area (defaults to window.innerWidth/innerHeight).
• worldWidth / worldHeight: The dimensions of the coordinate system being viewed.
• threshold: The number of pixels to move before triggering an input event like drag or pinch (default: 5).
• passiveWheel: Whether the 'wheel' event is passive (default: true).
• stopPropagation: Whether to stop propagation of events impacting the viewport (default: false).
• noTicker: If true, you must manually call update() on each frame.
• events: An instance of PIXI.EventSystem (required).
• ticker: The PIXI.Ticker used for updates (default: PIXI.Ticker.shared).
• disableOnContextMenu: If true, removes the default context menu behavior from the viewport's DOM element.

The Bounce plugin adds a bouncing effect when the viewport hits its edges. You can customize which sides trigger a bounce, the duration of the bounce, the easing function, and how the viewport behaves when the world is smaller than the screen (underflow).

IBounceOptions

The SnapZoom plugin allows the viewport to snap its zoom level to specific increments based on a target width or height. This is useful for creating 'fit-to-size' animations or snapping to specific zoom levels.

Options

Events

SnapZoom emits the following events on the Viewport instance:

• snap-zoom-start: Emitted when the snapping animation begins.
• snap-zoom-end: Emitted when the snapping animation reaches its target.

The Drag plugin enables panning of the viewport via mouse or touch. You can customize its behavior using IDragOptions when initializing the plugin.

Key configuration options include:

• direction: The axis to drag on ('all', 'x', or 'y'). Default is 'all'.
• pressDrag: Whether clicking/pressing triggers a drag. Default is true.
• mouseButtons: Which mouse buttons trigger dragging. Use 'all', 'left', 'right', 'middle', or combinations like 'middle-right'. Note: if using right-click, you may need to set viewport.options.disableOnContextMenu to true.
• keyToPress: An array of keyboard code strings (e.g., ['ShiftLeft']) that must be held to enable dragging.
• wheel: Whether to use the mouse wheel to scroll the viewport. Default is true.
• wheelScroll: Number of pixels to scroll per wheel spin. Default is 1.
• reverse: Reverses the wheel scroll direction. Default is false.
• underflow: Determines where to place the world if it is smaller than the screen. Options are 'center', or specific directions like 'left', 'right', 'top', 'bottom'. Default is 'center'.
• factor: A multiplier for drag speed. Default is 1.