pixi-scene-gif

GifSprite plays an animated GIF as a display object. Assets.load('animation.gif') returns a GifSource (not a Texture), and you wrap that in a GifSprite. Requires a side-effect import 'pixi.js/gif' to register the loader extension.

Assumes familiarity with pixijs-scene-core-concepts. GifSprite extends Sprite, so it is a leaf: do not nest children inside it. Wrap multiple GifSprite instances in a Container to group them.

Quick Start

import "pixi.js/gif";
import { GifSprite } from "pixi.js/gif";

const source = await Assets.load("animation.gif");

const gif = new GifSprite({
  source,
  autoPlay: true,
  loop: true,
  animationSpeed: 1,
});

gif.anchor.set(0.5);
gif.x = app.screen.width / 2;
gif.y = app.screen.height / 2;

app.stage.addChild(gif);

[!NOTE] GIFs decode every frame into a separate canvas texture. For performance-critical animations with many frames, prefer a spritesheet with AnimatedSprite — it uses a single atlas texture and batches better on the GPU.

Related skills: pixijs-scene-core-concepts (scene graph basics), pixijs-scene-sprite (AnimatedSprite for spritesheet-based animation), pixijs-assets (Assets.load, caching, unloading), pixijs-ticker (frame timing), pixijs-performance (texture memory).

Constructor options

GifSpriteOptions extends Omit<SpriteOptions, 'texture'>; texture is managed internally (set from source.textures[0] and swapped per frame). All other Sprite options (anchor, scale, tint, roundPixels, etc.) are valid, and all Container options (position, scale, tint, label, filters, zIndex, etc.) are also valid here — see skills/pixijs-scene-core-concepts/references/constructor-options.md.

Leaf-specific options added by GifSpriteOptions: