Skip to content
This repository


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

JavaScript GIF parser and player

branch: master

This branch is 0 commits ahead and 0 commits behind master

Merge pull request #1 from mmontag/disposal-mode-fix

Add support for disposal mode 2 and 3
latest commit 605c9a60e2
Andy yacomink authored
Octocat-spinner-32 example_gifs Update example August 29, 2012
Octocat-spinner-32 .gitignore Convert bookmarklet to a library, made rubbable, added example and docs. August 27, 2012
Octocat-spinner-32 LICENSE Add MIT license. October 01, 2011
Octocat-spinner-32 README.markdown Update example August 29, 2012
Octocat-spinner-32 example.html Update example August 29, 2012
Octocat-spinner-32 libgif.js Add support for disposal mode 2 and 3 November 03, 2013
Octocat-spinner-32 rubbable.js Changes from @llamerr for gifs in iframes October 08, 2013


Forked from the excelent jsgif project (, which was implemented as a bookmarklet to manipulate animated gifs (

This is an attempt to pull out the gif parsing and playing logic, seperate it from the bookmarklet, and publish it as a library that you can use in your project.

As an added bonus, you can make gifs "rubbable" so that scrubbing with your mouse (or rubbing with your finger on a touch device) cause the gif to move back and forth.


Please see example.html for, you know, and example. This will demonstrate how to use basic play controls for a gif, and also a rubbable one.

Please note: this example must be loaded via a webserver, not directly from disk. I.e. http://localhost/libgif-js/example.html NOT file:///libgif-js/example.html. See the same-domain origin caveat at the bottom of this document for more information.

For a hosted example, check out this post on (

Technical Details

Of note to the developer, libjs.gif contains a class SuperGif, which can be used to manipulate animated gifs.

Class: SuperGif

Example usage:

    <img src="./example1_preview.gif" rel:animated_src="./example1.gif" width="360" height="360" rel:auto_play="1" rel:rubbable="1" />

    <script type="text/javascript">
        $$('img').each(function (img_tag) {
            if (/.*\.gif/.test(img_tag.src)) {
                var rub = new SuperGif({ gif: img_tag } );
                    console.log('oh hey, now the gif is loaded');

Image tag attributes:

  • rel:animated_src - If this url is specified, it's loaded into the player instead of src. This allows a preview frame to be shown until animated gif data is streamed into the canvas

  • rel:auto_play - Defaults to 1 if not specified. If set to zero, a call to the play() method is needed

  • rel:rubbable - Defaults to 0 if not specified. If set to 1, the gif will be a canvas with handlers to handle rubbing.

Constructor options

  • gif - Required. The DOM element of an img tag.
  • auto_play - Optional. Same as the rel:auto_play attribute above, this arg overrides the img tag info.
  • max_width - Optional. Scale images over max_width down to max_width. Helpful with mobile.
  • rubbable - Optional. Make it rubbable.

Instance methods


  • load( callback ) - Loads the gif into a canvas element and then calls callback if one is passed

play controls

  • play - Start playing the gif
  • pause - Stop playing the gif
  • move_to(i) - Move to frame i of the gif
  • move_relative(i) - Move i frames ahead (or behind if i < 0)


  • get_canvas - The canvas element that the gif is playing in. Handy for assigning event handlers to.
  • get_playing - Whether or not the gif is currently playing
  • get_loading - Whether or not the gif has finished loading/parsing
  • get_auto_play - Whether or not the gif is set to play automatically
  • get_length - The number of frames in the gif
  • get_current_frame - The index of the currently displayed frame of the gif

Caveat: same-domain origin

The gif has to be on the same domain (and port and protocol) as the page you're loading.

The library works by parsing gif image data in js, extracting individual frames, and rendering them on a canvas element. There is no way to get the raw image data from a normal image load, so this library does an XHR request for the image and forces the MIME-type to "text/plain". Consequently, using this library is subject to all the same cross-domain restrictions as any other XHR request.

Something went wrong with that request. Please try again.