Animated GIF Player Plugin With jQuery Or Vanilla JS - freezeframe.js

File Size: 1.61 MB
Views Total: 9251
Last Update:
Publish Date:
Official Website: Go to website
License: MIT
Animated GIF Player Plugin With jQuery Or Vanilla JS - freezeframe.js

freezeframe.js is a fancy touch-enabled JavaScript/jQuery GIF player that allows to manually play an animated GIF frame by frame with custom trigger events/elements.

Supports responsive images and mobile touch events. Heavily based on Html5 Canvas technique.

Note that the latest freezeframe.js (v4.0+) has dropped the jQuery support. You can also use it as a jQuery plugin. Download Here.

See also:

Table Of Contents:

How to use it (Vanilla JS Version):

1. Install the package and import the freezeframe as an ES module.

# Yarn
$ yarn add freezeframe

$ npm i freezeframe --save
import Freezeframe from 'freezeframe';

2. Or load the freezeframe.min.js script from local.

<script src="dist/freezeframe.min.js"></script>

3. Add the CSS class freezeframe to the GIF image or a container consist of a group of GIF images as follows.

<img class="freezeframe" src="example.gif" />

<div class="freezeframe">
  <img src="example1.gif">
  <img src="example2.gif">
  <img src="example3.gif">

4. Initialize the freezeframe.js plugin and done.

new Freezeframe();

5. Set the trigger event to play/pause the GIF animation. Default: 'hover'.

new Freezeframe({
    trigger: 'click'

6. Add a play button to the GIF image. Default: false.

new Freezeframe({
    overlay: true

7. Play/pause the GIF animation manually.

const manual = Freezeframe({
      trigger: false


8. Make the image full responsive. Default: true.

new Freezeframe({
    responsive: true

9. Override the default seletor. Default: '.freezeframe'.

  selector: '.another'

// or
  // options here

How to use it (jQuery Version):

1. First you need to load the latest version of jQuery JavaScript library in the html document.

<script src="//"></script>

2. Download the freezeframe.js (jQuery Version) and then load the jQuery freezeframe.js plugin's JavaScript and CSS in the document. Note that the freezeframe.min.js must be loaded after jQuery library.

<link rel="stylesheet" href="freezeframe_styles.min.css">
<script src="freezeframe.min.js"></script>

3. Just call the function on the GIF's parent container and done. By default, the plugin will pause the GIF and play it on mouse hover.


// or
var instance = new freezeframe({
  'selector': '.selector'

4. Default plugin options.


  // The selector freezeframe will use to search for .gifs when the capture() function is run (if no custom selector is passed to the capture() function).
  selector : '.freezeframe',

  // The number of milliseconds a .gif will animate for when triggered by click / touch event.
  animation_play_duration: 5000,

  // 'hover' or 'click'
  non_touch_device_trigger_event: 'hover'

5. Play & pause the GIF.

// play

// stop

6. More API methods.

// Creates and inserts support elements.
instance.setup( selector );

// Attaches hover / click / touch events
instance.attach( selector );


v5.0.1 (2021-02-01)

v5.0.1 (2021-01-16)

  • update

v5.0.0 (2021-01-11)

  • Freezeframe is now written in / supports TypeScript! The library will still support usage in JavaScript, but if your project uses TypeScript, you'll have access to Freezeframe's type definitions, improved input validation, and depending on your IDE/text editor, autocompletion/intellisense.


  • v4.1.0


  • v4.0.0
  • Doc updated


  • v3.0.10: fixed mobile issue


  • v3.0.9: fixed overlay class toggle issue


  • v3.0.8

This awesome jQuery plugin is developed by ctrl-freaks. For more Advanced Usages, please check the demo page or visit the official website.