How to Pause a GIF with the freezeframe.js Library

Written by
Typical Read
5 minutes

freezeframe.js is a modern JS library that uses canvas to easily allow pausing and playing of GIF animations. In this article, I'll show you how to pause a GIF, then play on command using mouse events — or by triggering it manually.

Learn how to pause a GIF & play using the freezeframe.js library — a JS library that pauses animated .gifs and enables them on command. Control GIFs with mouse hovers, clicks, touch events or trigger and release functions.

What is a GIF? A GIF or Graphics Interchange Format is a bitmap image format — often used for animated raster graphics — that was developed by a team at the online services provider CompuServe led by American computer scientist Steve Wilhite on June 15, 1987.

How to Pause a GIF using freezeframe.js

Controlling a GIF like you would a video isn’t as easy as a click of the mouse — until now. Introducing freezeframe.js. A light-weight JS library that uses canvas to mimic the functionality videos have, pausing and playing.

Freezeframe.js is a library that pauses animated .gifs and enables them to animate on mouse hover / mouse click / touch event, or triggered manually.

With this JS library, you’ll know how to pause a GIF by writing its data to a canvas element — automatically. Only the first frame of the animation can be written to canvas, which results in a frozen version of the gif. Now you can control the animation a frame at a time using mouse events or manual triggers.

Not a fan of the JS solution? You can also mimic the pausing and playing GIFs with just CSS or even better, an accessible way using the summary/details element.

Installing freezeframe.js

How to pause a GIF with freezeframe.js

To get started, you’ll need to install the freezeframe.js library on your app. If your project supports ES6 modules or commonjs modules, install via npm or yarn:

Install with npm:

npm install freezeframe

Install with yarn:

yarn add freezeframe

Or link directly to it using the CDN version:

For rapid development, freezeframe.js offers a CDN version that you can load to avoid having to install directly on your application

<script src=""></script>

Setting Up freezeframe.js

Now the fun part. Once you’ve got freezeframe.js installed, it’s time to start controlling the GIF. Here’s how you can pause a GIF then play on command — just add the freezeframe class (or a custom selector) to the GIFs you’d like control over. It’s that easy!

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

That’s it! Now you know how to pause a GIF and then play on command with a simple, light-weight JS library.

Now let’s dig a little deeper on how to pause a GIF using multiple GIFs and advanced configuration.

Multiple GIFs in a single container?

It’s also possible to put the freezeframe class on a parent element containing as many GIFs as you want:

<div class="freezeframe">
  <img src="image1.gif" />
  <img src="image2.gif" />
  <img src="image3.gif" />

Need more advanced configuration? freezeframe.js also exposes public methods to allow for more custom integration.

Advanced freezeframe.js Usage

Let’s go over how to pause a GIF then play with freezeframe.js public methods. These methods allow you the ability to manually control when freezeframe triggers images, adds support elements, and attaches event handlers. You can also manually trigger and release animation on one image or a group of images.

Here’s an example of how to pause GIFs then play them using it’s methods:

// setup freezeframe instance with custom selector and options
const logo = new Freezeframe('#logo', {
  trigger: false
logo.start(); // start animation
logo.stop(); // stop animation
logo.toggle(); // toggle animation

freezeframe.js Options

Check out the available public methods below on how to pause a GIF, then play as needed:

Type: string | DOM object
Default: ".freezeframe"

The selector used to search for .gifs to freeze. Selector may either be passed as the first argument of the Freezeframe constructor, or as a property of the options object. You may pass a string selector or a DOM reference. If a string is passed, we use querySelectorAll.

Type: string | boolean
Default: "hover"
Options: "hover", "click", false

The trigger event to start animation for non-touch devices.

Type: boolean
Default: false

Whether or not to display a play icon on top of the paused image.

Type: boolean
Default: true

Whether or not to make the image responsive (100% width)

Type: boolean
Default: true

Whether or not to console.warn if image doesn’t appear to be a gif. When using gifs that don’t end in .gif, or animated pngs, you may want to disable these.

freezeframe.js Methods


Start animation, or restarts animation from the first frame if the .gif is already animating.

// first, save a reference to your freezeframe instance
const ff = new Freezeframe({
  trigger: false

How to pause a GIF animation.


How to pause a GIF & play toggling based on its current state.

on(event, callback)

Add event listeners to a freezeframe instance.

  • event

    type: string
    options: start|stop|toggle

  • callback

    type: function

    • items: array | freezeframe
    • isPlaying: boolean

An example of how to pause a GIF then play while listening for events:

ff.on('start', (items) => {
  // do something on start
ff.on('stop', (items) => {
  // do something on stop
ff.on('toggle', (items, isPlaying) => {
  if (isPlaying) {
    // do something on start
  } else {
    // do something on stop

Removes all event listeners, but leaves DOM intact. Use if you are concerned about memory leaks on your event listeners.


How you know how to pause a GIF & play on command, what are you going to build with it?

Now that you know how to pause a GIF and play on command with the freezeframe.js library — what are you going to build with it? Comment below with how you used this light-weight library to enhance you applications UX.

1 comment on “How to Pause a GIF with the freezeframe.js Library”.


# Jan 27, 2021

When it stops, it’s resizing the image, I solve it using:
.ff-inactive {
width: 200px !important;

Join the conversation.

Your email address will not be published. Required fields are marked *

All comments posted on 'How to Pause a GIF with the freezeframe.js Library' are held for moderation and only published when on topic and not rude. Get a gold star if you actually read & follow these rules.

You may write comments in Markdown. This is the best way to post any code, inline like `<div>this</div>` or multiline blocks within triple backtick fences (```) with double new lines before and after.

Want to tell me something privately, like pointing out a typo or stuff like that? Contact Me.