This is the main entrypoint to the library.

Prepares and sends an XHR request to load the GIF file.

Returns a Gif instance for interacting with the library.


url URL to .gif file


a Gif instance object


Animates the loaded GIF, drawing each frame into the canvas. This matches the look of an <img> tag.


selector A <canvas> element or query selector for a <canvas> element.


Runs the animation on the loaded GIF, but passes the canvas context and GIF frame to the onDrawFrame callback for rendering.

This gives you complete control of how the frame is drawn into the canvas context.


selector A <canvas> element or query selector for a <canvas> element.
onDrawFrame A callback that will be invoked when each frame should be drawn into the canvas. see Animator.onDrawFrame.
setDimesions OPTIONAL. If true, the canvas's width/height will be set to the dimension of the loaded GIF. default: false.


To get even more control, and for your convenience, this method returns a promise that will be fulfilled with an Animator instance. The animator will be in an unstarted state, but can be started with a call to animator.animateInCanvas()


Creates a buffer canvas element since it is much faster to call .putImage() than .putImageData().

The omggif library decodes the pixels into the full gif dimensions. We only need to store the frame dimensions, so we offset the putImageData call.


frame A frame of the GIF (from the omggif library)
width width of the GIF (not the frame)
height height of the GIF


A <canvas> element containing the frame's image.


Starts running the GIF animation loop.


Stops running the GIF animation loop.


Resets the animation loop to the first frame.

Does not stop the animation from running.



A boolean indicating whether or not the animation is running.


This method prepares the canvas to be drawn into and sets up the callbacks for each frame while the animation is running.

To change how each frame is drawn into the canvas, override animator.onDrawFrame() before calling this method. If animator.onDrawFrame() is not set, we simply draw the frame directly into the canvas as is.

You may also override animator.onFrame() before calling this method. onFrame handles the lazy construction of canvas buffers for each frame as well as the disposal method for each frame.


canvas A canvas element.
setDimensions OPTIONAL. If true, the canvas width/height will be set to match the GIF. default: true.