Categories: CSSScriptWeb Design

Accessible GIF Image Player In Vanilla JavaScript – Gifa11y

Gifa11y is a Vanilla JavaScript library that adds configurable, accessible play/pause buttons to animated Gif/WebP images.

Table of Contents

Toggle

How to use it:

1. Import the gifa11y.js library into the document.

<script src="gifa11y.umd.min.js"></script>

2. Initialize the Gifa11y library and specify the container element that holds your GIFs.

var gifa11y = new Gifa11y({
    container: '.container'
});

3. That’s it. The library will automatically add play/pause buttons to the GIFs inside the ‘container’.

4. Auto pause the GIF on initial load. When enabled, the library generates a preview image from the GIF’s first frame using HTML canvas.

<img loading="lazy" 
     src="demo.gif" 
     class="gifa11y-paused" 
     alt="Example GIF"
>

5. Ignore specified GIFs using the ‘gifa11y-ignore’ class.

<img loading="lazy" 
     src="demo.gif" 
     class="gifa11y-ignore" 
     alt="Example GIF"
>

6. Available options.

var gifa11y = new Gifa11y({

    // Button styles
    buttonBackground: 'indigo',
    buttonBackgroundHover: 'rebeccapurple',
    buttonBorder: '2px solid #fff',
    buttonIconColor: 'white',
    buttonFocusColor: '#00e7ffad',
    buttonSvgSize: '1.5rem',
    buttonIconFontSize: '1rem',
    buttonPlayIconID: ' ',
    buttonPauseIconID: ' ',
    buttonPlayIconHTML: ' ',
    buttonPauseIconHTML: ' ',

    // Container
    container: 'body',

    // Ignore specific GIFs or regions
    exclusions: '',

    // Ignore specific containers
    gifa11yOff: '.gifa11y-off',

    // Inherit classes
    inheritClasses: true,

    // Pause GIFs on initial load
    initiallyPaused: false,

    // Warn content author if they are missing an alt attribute on GIF
    missingAltWarning: true,

    // Pausing any gif pauses all gifs.
    sharedPauseButton: false,

    // Show or hide Play/Pause buttons.
    showButtons: true,

    // Show or hide GIF text within buttons
    showGifText: false,

    // Using CSS selectors to target other images 
    target: '',

    // i18n
    langPause: 'Pause animation:',
    langPlay: 'Play animation:',
    langPauseAllButton: 'Pause all animations',
    langPlayAllButton: 'Play all animations',
    langMissingAlt: 'Missing image description.',
    langAltWarning: '&#9888; Error! Please add alternative text to GIF.',
    
});

7. Create a button to play/pause all GIFs.

<button id="gifa11y-all">Pause/Play All GIFs</button>

8. API methods.

// Programmatically play/pause Gifa11y.
window.gifa11y.setAll(myOtherAnimationsPlaying ? 'playing' : 'paused');

// Find new GIFs
window.gifa11y.findNew();

Changelog:

v2.2.0 (05/16/2025)

  • Slight change in behaviour for the target prop. It now has a default value of img[src$=”.gif”], which means the query selector can now be overridden or used to add additional images to target, for example pass target: ‘img[src$=”.gif”], img[src$=”.webp”]’ to query all GIFs and .webp images.

v2.1.0 (01/28/2025)

  • New prop: sharedPauseButton is an alternative to a toggle all gifs button. Setting this prop to true makes all buttons act like the “toggle all” button, where pressing pause on one gif will pause the remaining gifs on the page.
  • New: window.gifa11y.setAll() allows your to programatically set playing or paused state.
  • New: window.gifa11y.findNew(); tells Gifa11y to find new gifs on the page and add a play/pause button.

v2.0.4 (11/20/2024)

  • Update

v2.0.3 (01/08/2024)

  • Buttons are now encapsulated within a web component to avoid CSS conflicts.
  • New prop buttonBorder to change properties of a play/pause button’s border.

v2.0.2 (06/14/2023)

  • Refactored & modularized. Less spaghetti code.
  • Added dev tooling & CSS/JavaScript linting.
  • New props and button style.

v1.0.6 (08/23/2022)

  • Bug fix. Resolve maincontainer === undefined.

07/01/2022

  • Add vertical-align: middle to SVG icon. Remove .webp support. Animated webp is less common then GIF. In more cases, webp files are usually static images.

01/08/2022

  • Add fallback when canvas.clientWidth equals 0

12/14/2021

  • Support for WebP

The post Accessible GIF Image Player In Vanilla JavaScript – Gifa11y appeared first on CSS Script.