PNG Sequencer

import PngSequencer from '@bbc/front-end-kit/js/components/PngSequencer';

The PngSequencer is a JavaScript class that allows you to quickly set up an element to show and manage a PNG sequence. With the help of GSAP, you can easily play animations to a given index or progress value.

Getting Started

import PngSequencer from '@bbc/front-end-kit/js/components/PngSequencer';

const myPngSequencer = new PngSequencer({
    $el: document.querySelector('.my-element'),
    frameCount: 60,
    duration: 3,
    imageUrl: 'path/to/images/frame_{{index}}.png',
});

This will create a new instance of the PngSequencer class and set it up to manage a PNG sequence with 60 frames, a duration of 3 seconds, and images located at the specified URL.

API

constructor(args = {})

The constructor method initialises the new PngSequencer instance. It automatically calls loadImages() and resizeCanvas() during construction and sets up a ResizeObserver to re-render when the container size changes.

Parameters

• $el (Element, optional): The DOM element that will contain the PNG sequence. If not provided, a new div element is created.
• frameCount (Number): The number of frames in the sequence.
• duration (Number): The duration of the full sequence in seconds.
• imageUrl (String): The URL template for the images, with {{index}} as a placeholder for the frame number (zero-padded to match frameCount digit length).
• index (Number, optional): The index of the initial frame. No default — if omitted, the first render() call will fail because images[undefined] is invalid. Always provide this.
• timeScale (Number, optional): The time scale of the GSAP timeline. Default: 1.

Methods

loadImages()

Loads all frames by constructing image URLs from imageUrl with the frame number substituted for {{index}}. Calls render() once the first image has loaded.

resizeCanvas()

Removes any existing canvas, creates a new DPI-scaled one matching the container's bounding rect, and calls render().

play(value = null)

Convenience method:

• null → plays to the last frame
• 0 < value < 1 → delegates to playToProgress(value)
• 0 or >= 1 → delegates to playToIndex(value)

playToIndex(index)

Tweens the sequence to the given frame index over a proportional duration. No-ops if already at that index. Dispatches tween-refresh when the tween starts.

playToProgress(progress)

Converts a 0–1 progress value to an index and delegates to playToIndex. No-ops if progress is outside 0–1.

render()

Draws the current frame (this._images[this.index]) onto the canvas. Called automatically by the index setter on every frame change.

destroy()

Disconnects the ResizeObserver.

Getters & Setters

$el (get)

Returns the root container element.

index (get / set)

Gets or sets the current frame index. The setter floors the value, clamps it within 0–frameCount-1 (with loop-around), and calls render().

duration (get)

Returns the total duration of the sequence in seconds.

frameCount (get)

Returns the total number of frames.

progress (get / set)

Gets or sets the playback position as a 0–1 value. The setter converts to an index and delegates to the index setter.

timeline (get)

Returns the GSAP timeline instance.

Events

tween-refresh

Dispatched by playToIndex each time a new tween is started.

tweenCompleted

Dispatched when a tween finishes playing to its target index.

External dependencies

• GSAP: Used for tweening between frame indices.