Skip to content
JavaScript GIF parser and player
JavaScript HTML
Branch: master
Clone or download
This branch is 51 commits ahead of shachaf:master.

Latest commit

Latest commit 0654e7f Mar 11, 2016


Type Name Latest commit message Commit time
Failed to load latest commit information.
example_gifs Update example Aug 29, 2012
.gitignore Convert bookmarklet to a library, made rubbable, added example and docs. Aug 27, 2012
LICENSE Add MIT license. Oct 2, 2011
README.markdown fix typo in README Mar 10, 2016
example.html Add options to customize progressbar. Jan 15, 2016
libgif.js Merge pull request #13 from YuheiNakasaka/fix-getter Mar 7, 2016
rubbable.js Added AMD and CommonJS support Feb 24, 2015



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, an 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.
  • loop_mode - Optional. Setting this to false will force disable looping of the gif.
  • 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.
  • on_end - Optional. Add a callback for when the gif reaches the end of a single loop (one iteration). The first argument passed will be the gif HTMLElement.
  • loop_delay - Optional. The amount of time to pause (in ms) after each single loop (iteration).
  • progressbar_height - Optional. The height of the progress bar.
  • progressbar_background_color - Optional. The background color of the progress bar.
  • progressbar_foreground_color - Optional. The foreground color of the progress bar.

Instance methods


  • load( callback ) - Loads the gif specified by the src or rel:animated_src sttributie of the img tag into a canvas element and then calls callback if one is passed
  • load_url( src, callback ) - Loads the gif file specified in the src argument 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.

You can’t perform that action at this time.