pixijs-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

Option	Type	Default	Description
`source`	`GifSource`	—	Required. The parsed GIF data returned by `Assets.load('file.gif')` . Can be shared across multiple `GifSprite` instances.
`autoPlay`	`boolean`	`true`	Start playback immediately on construction. If `false` , you must call `gif.play()` to begin.
`loop`	`boolean`	`true`	Repeat the animation on reaching the last frame. When `false` , the sprite stops at the final frame and fires `onComplete` .
`animationSpeed`	`number`	`1`	Multiplier on the GIF's native frame timing. `2` runs at double speed; `0.5` runs at half.
`autoUpdate`	`boolean`	`true`	Connect playback to `Ticker.shared` . Set to `false` to drive updates yourself via `gif.update(ticker)` .
`fps`	`number`	`30`	Fallback frame rate for GIFs that do not specify per-frame delays.
`onComplete`	`() => void \| null`	`null`	Called when a non-looping animation reaches the last frame.
`onLoop`	`() => void \| null`	`null`	Called each time a looping animation wraps around.
`onFrameChange`	`(frame: number) => void \| null`	`null`	Called every time the displayed frame index changes.
`scaleMode`	`SCALE_MODE`	`'linear'`	Deprecated since 8.13.0 — pass `scaleMode` via `Assets.load(..., { data: { scaleMode } })` instead.

The constructor also accepts a bare

GifSource

as its sole argument (

new GifSprite(source)

), which is shorthand for

new GifSprite({ source })

using the defaults above.

Core Patterns

Setup and the side-effect import

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

const source = await Assets.load("animation.gif");
const gif = new GifSprite({ source });

pixi.js/gif

calls

extensions.add(GifAsset)

, registering

.gif

with the asset loader. Without it,

Assets.load

does not recognize GIF files.

GifSprite

and

GifSource

are exported from

pixi.js/gif

, not

pixi.js

Importing a named export from

pixi.js/gif

also triggers the side effect, so a bare

import 'pixi.js/gif'

is only needed when you don't import anything from that path.

Playback control

const gif = new GifSprite({ source });

gif.play();
gif.stop();

gif.currentFrame = 5;
gif.animationSpeed = 2;
gif.animationSpeed = 0.5;

gif.playing; // read-only
gif.progress; // 0-1 playback position
gif.totalFrames; // number of frames
gif.duration; // total duration in ms

autoPlay: true

(default) starts playback immediately;

loop: true

(default) repeats.

animationSpeed

is a multiplier on the GIF's native frame timing.

currentFrame

is zero-based.

Loading options

const source = await Assets.load({
  src: "animation.gif",
  data: {
    fps: 12,
    scaleMode: "nearest",
    resolution: 2,
  },
});

const fromDataUri = await Assets.load("data:image/gif;base64,R0lGODlh...");

Options in

data

are passed to

GifSource.from

fps

sets the fallback frame delay for GIFs that don't specify timing.

scaleMode

and

resolution

control the canvas textures created for each frame. The loader matches both

.gif

file extensions and

data:image/gif

URIs.

Callbacks

const gif = new GifSprite({
  source,
  loop: false,
  onComplete: () => console.log("animation finished"),
  onLoop: () => console.log("loop completed"),
  onFrameChange: (frame) => console.log("now on frame", frame),
});

```
onComplete
```
fires when a non-looping animation reaches the last frame.
```
onLoop
```
fires each time a looping animation wraps around.
```
onFrameChange
```
fires every time the displayed frame changes.

Manual update mode

const gif = new GifSprite({ source, autoUpdate: false });

app.ticker.add((ticker) => {
  gif.update(ticker);
});

autoUpdate: false

disconnects from

Ticker.shared

. You call

gif.update(ticker)

yourself, passing any

Ticker

instance. Useful when animation should be driven by a private ticker (e.g., a pause-aware game ticker).

Sharing source data and cloning

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

const gif1 = new GifSprite({ source, autoPlay: true });
const gif2 = new GifSprite({ source, autoPlay: false });

const gif3 = gif1.clone();
gif3.animationSpeed = 0.5;

GifSource

can be shared across multiple

GifSprite

instances; each sprite has independent playback state.

clone()

copies all playback settings but creates an independent instance.

Common Mistakes

[HIGH] Not importing pixi.js/gif

Wrong:

import { Assets } from "pixi.js";
const gif = await Assets.load("animation.gif");

Correct:

import "pixi.js/gif";
import { Assets } from "pixi.js";
const source = await Assets.load("animation.gif");

The GIF loader extension must be registered before loading. Without the side-effect import, the loader does not recognize

.gif

files and the load either fails or returns raw data.

[MEDIUM] Expecting Assets.load to return a Texture

Wrong:

const texture = await Assets.load("animation.gif");
const sprite = new Sprite(texture);

Correct:

const source = await Assets.load("animation.gif");
const gif = new GifSprite({ source });

Assets.load

on a GIF returns a

GifSource

containing frame textures and timing data. Pass the source to

GifSprite

; for a single still frame, read

source.textures[0]

[MEDIUM] GIF memory not released on destroy

Wrong:

gif.destroy();
// GifSource and frame textures remain in memory

Correct:

gif.destroy(true);
// or
await Assets.unload("animation.gif");

GIF frames hold decoded pixel data as individual canvas textures.

gif.destroy()

(or

destroy(false)

) destroys the sprite but keeps the

GifSource

intact. Pass

true

to also destroy the source. For shared sources, only destroy when the last consumer is done, or call

Assets.unload

to let the asset cache handle it.

[LOW] Do not nest children inside a GifSprite

GifSprite

extends

Sprite

, which sets

allowChildren = false

. It is a leaf. To group a GIF with other display objects, wrap them all in a plain

Container

const group = new Container();
group.addChild(gif, label);

pixijs-scene-gif

NPX Install

Tags

SKILL.md Content

Quick Start

Constructor options

Core Patterns

Setup and the side-effect import

Playback control

Loading options

Callbacks

Manual update mode

Sharing source data and cloning

Common Mistakes

[HIGH] Not importing pixi.js/gif

[MEDIUM] Expecting Assets.load to return a Texture

[MEDIUM] GIF memory not released on destroy

[LOW] Do not nest children inside a GifSprite

API Reference