gif.js

library0.2.0jsnpmunverified

gif.js is a client-side JavaScript library designed for encoding GIFs directly in the browser. It leverages modern browser APIs like Web Workers and Typed Arrays to perform image processing in the background, aiming for fast performance without blocking the main thread. Despite its original aim for efficiency, the project's last stable version is 0.2.0, released over a decade ago (published in 2016, last commit 2017). This indicates it has a virtually non-existent release cadence and is no longer actively maintained. Its key differentiators at the time were its browser-centric approach with Web Worker offloading, which was a significant performance advantage for client-side GIF generation compared to synchronous methods. It accepts image elements, canvas elements, or canvas contexts as frames. However, newer alternatives often offer better performance via WebAssembly and more modern API designs.

serialization

npm install gif.js

github ↗package ↗

INSTALL

IMPORT

SIG · GIF.JS

gif.js

serializationjavascriptv0.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

GIF

✓  <script src="dist/gif.js"></script> <script> var gif = new GIF({ workers: 2, quality: 10 }); </script>

✗ import { GIF } from 'gif.js';

gif.js is primarily designed for inclusion via a `<script>` tag, exposing the `GIF` constructor globally. It does not natively support ES module imports.

gif.worker.js

✓  <script src="dist/gif.js"></script> <script> var gif = new GIF({ workerScript: '/path/to/gif.worker.js' // If not in same directory }); </script>

The library relies on a separate web worker script, `gif.worker.js`, which must be accessible at runtime. By default, it expects it in the same directory as `gif.js`.

This quickstart demonstrates how to initialize GIF.js, add frames from an image element, a canvas element, and directly from a canvas rendering context. It then renders the GIF and displays it on the page.

<html> <head> <title>GIF.js Quickstart</title> <script src="https://cdn.jsdelivr.net/npm/gif.js@0.2.0/dist/gif.js"></script> </head> <body> <canvas id="myCanvas" width="200" height="200"></canvas> <img id="myImage" src="https://via.placeholder.com/200x200.png?text=Frame+1" style="display:none;" alt="Frame 1"/> <button id="renderGif">Render GIF</button> <script> const canvas = document.getElementById('myCanvas'); const ctx = canvas.getContext('2d'); const image1 = document.getElementById('myImage'); const gif = new GIF({ workers: 2, quality: 10, width: 200, height: 200, repeat: 0 // loop forever }); // Add frame from an image element gif.addFrame(image1, { delay: 500 }); // Add frame from a canvas element (draw something first) ctx.fillStyle = 'blue'; ctx.fillRect(50, 50, 100, 100); gif.addFrame(canvas, { delay: 500 }); // Add another frame by clearing and drawing something else ctx.clearRect(0, 0, canvas.width, canvas.height); ctx.fillStyle = 'red'; ctx.beginPath(); ctx.arc(100, 100, 50, 0, Math.PI * 2); ctx.fill(); gif.addFrame(ctx, { copy: true, delay: 500 }); // copy: true is important for context gif.on('finished', function(blob) { const img = document.createElement('img'); img.src = URL.createObjectURL(blob); document.body.appendChild(img); console.log('GIF rendered!'); }); document.getElementById('renderGif').addEventListener('click', () => { console.log('Rendering GIF...'); gif.render(); }); </script> </body> </html>

Debug

Known issues

gotchaThe `gif.worker.js` file is essential for the library to function, as it offloads frame processing to Web Workers. If this file is not found at the expected path, GIF generation will fail silently or with worker-related errors.

fix

Ensure `gif.worker.js` (from the `dist/` folder) is deployed to the same directory as `gif.js` on your web server, or specify its exact URL using the `workerScript` option in the `GIF` constructor: `new GIF({ workerScript: '/path/to/gif.worker.js' })`.

affects: >=0.1.0

breakingThe project is abandoned, with the last update over a decade ago. It lacks modern features, performance optimizations found in newer libraries (e.g., WebAssembly-based encoders), and security updates. It may not integrate well with modern JavaScript module systems (ESM) and build tools.

fix

For new projects, consider modern alternatives that are actively maintained and offer better performance, broader browser support, and module compatibility. For existing projects, be aware of potential limitations and lack of security patches.

affects: >=0.2.0

gotchagif.js relies on specific browser features: Web Workers, File API, and Typed Arrays. Older browsers or environments that do not fully support these features will prevent the library from working correctly.

fix

Verify target browser compatibility for Web Workers, File API, and Typed Arrays. For broader support, consider using a polyfill library or a different GIF encoding solution that targets older browser versions.

affects: >=0.1.0

gotchaWhen adding a frame directly from a CanvasRenderingContext2D (e.g., `ctx`), the `copy: true` option is crucial. If omitted, the library might try to use a reference to the context's current state, which could lead to unexpected or blank frames if the canvas content changes before the worker processes the frame.

fix

Always use `gif.addFrame(ctx, { copy: true, delay: 500 });` when providing a canvas context to ensure a snapshot of the pixel data is taken at the time of `addFrame` call.

affects: >=0.1.0

Errors

Common errors & fixes

ReferenceError: GIF is not defined

The `gif.js` script was not loaded into the HTML page, or was loaded incorrectly, meaning the global `GIF` constructor is not available.

fix

Ensure you have `<script src="dist/gif.js"></script>` in your HTML file, typically before your own scripts that try to use `GIF`. Verify the path to `gif.js` is correct.

Uncaught ReferenceError: GIFWorker is not defined at ... (gif.js:X)

The `gif.worker.js` file, which is crucial for the library's functionality, could not be found or loaded by the browser.

fix

Place `gif.worker.js` (from the `dist/` folder of the package) in the same directory as your `gif.js` file, or explicitly configure its path using the `workerScript` option when initializing `GIF`: `new GIF({ workerScript: '/path/to/gif.worker.js' })`.

The image is blank, or frames are incorrect/missing in the output GIF.

This can happen due to various reasons, including incorrect frame data, asynchronous image loading, or not specifying `copy: true` when adding frames from a canvas context that changes.

fix

Ensure all image elements are fully loaded before adding them as frames. If using a canvas context, always add `copy: true` to `addFrame` options: `gif.addFrame(ctx, { copy: true })`. Also, check the `width` and `height` options; if `null`, they are determined by the first frame, which might be an issue if the first frame is invalid or not yet ready.

Upgrade

Version history

0.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/jnordberg/gif.js ↗

packagehttps://www.npmjs.com/package/gif.js ↗