Awesome Open Source
Awesome Open Source

gandul! šŸ˜“ (accessible-image-lazy-load)

MIT license NPM Version File Size Twitter

Accessible lazy loading images

gandul šŸ˜“ is a lightweight (<2Kb) non-dependant javascript module that adds a different approach on lazy loading focusing on accessibility. Most existing options work by either making you drop the src attribute of the image or, making you create a base64 data / low resolution blurred alternative version of the image, or also including the img element into a <noscript> tag. This could be hacky and verbose and the main issue with it is that alters the semantics of the original element.

In order to avoid that, gandul šŸ˜“ works by taking a common anchor hyperlink <a> as the data source of the image to be loaded and transforms it into a <img> element. This way you don't lose the reference to the image you want to show and, in case there's no JavaScript, your image will still be accessible by users and crawlers.

Basic Example :

<!-- How your HTML will look like: -->
<a href="" class="gandul">Nice kitten</a>

<!-- What the gandul script will output : -->
<img src="" class="gandul" alt="Nice kitten" />
HTML Input gandul šŸ˜“ Output
<a href="" class="gandul">Nice kitten</a> <img src="" class="gandul" alt="Nice kitten" />
Nice kitten Nice kitten

How to use it

1. Download the script

You have multiple options to get gandul šŸ˜“ ( gandul.min.js ):

2. Get it working

Write an anchor hyperlink with the reference to your image and set the class gandul on it (<a class="gandul">). then, include and call the script :

<!-- How a gandul image reference looks like -->
<a href="" class="gandul">Nice kitten</a>

<!-- Include and call the script -->
<script src=""></script>

Image Attributes

gandul šŸ˜“ will take all the existing attributes on the <a> element and they will be passed to the newly created <img> with a few peculiarities, as <a> elements don't have srcset, sizes, width... attributes, those will be passed as data attributes. Right below you can see the equivalences table and some examples:

In case you want to apply gandul to a different HTML element than a hyperlink (<a>) the image source will be taken from the data-href attribute

<a> attributes <img> attributes equivalence
Anchor hyperlink inner text. alt
href src
data-href src
data-srcset srcset
data-sizes sizes
data-width width

Fully responsive image example:

<!-- Write your hyperlink HTML as it follows : -->
<a href=""
   data-srcset=" 320w,
   data-sizes="(max-width: 320px) 280px, (max-width: 480px) 440px, 800px"
   class="gandul">Nice kitten</a>

<!-- To get a responsive image output like this one: -->
<img src=""
	 srcset=" 320w,
     sizes="(max-width: 320px) 280px, (max-width: 480px) 440px, 800px"
     alt="Nice kitten" />

Setting just the width attribute of an image :

<!-- What you'll write: -->
<a href="" data-width="800" class="gandul">Nice kitten</a>

<!-- What you'll get : -->
<img src="" width="800" alt="Nice kitten" />

Any other attributes :

Any other attributes will remain as they are, which means that if you already set or you need on the <img> an id or different classes, those will be passed through the gandul šŸ˜“ script :

<!-- input -->
<a href="" id="cat" class="nice kitten gandul">Nice kitten</a>

<!-- gandul output -->
<img src="" id="cat" class="nice kitten gandul" alt="Nice kitten" />


Some parameters can be send to the gandul šŸ˜“ function:

gandul(target, opts, action);
  • target (@string) : a selector targeting all the elements where you want the script to get executed. It defaults to all anchor hyperlinks with the classname gandul : "a.gandul"
  • opts (@object) : an options object containing the fields used by the IntersectionObserver constructor
    • root : element used as viewport of the target. Default value is the brwoser viewport (null)
    • rootMargin : margin of root element to grow or shrink the intersection. Default value takes an extra 50 pixels above and below the viewport ("50px 0px 50px 0px").
    • threshold : percentage of target visibility to trigger the action. Default is 0.
  • action (@function) : A callback function to be executed when the image finishes loading after the target has intersected the given viewport, it comes with image element itself as first parameter (function(img){ /* console.log(img) */ }). The default action when image loads is to attach to the img element the class named 'gandul-active'.

The following example makes use of some of these options, it will target all hyperlinks with the class gandul-hyperlink, will be activated when 50% of the target element is visible and the function used as callback will change the created image border style as defined below:

gandul('a.gandul-hyperlink', { threshold: .5 }, function(img) { = 'solid red 10px';


# Clone the repo
$ git clone
$ cd accessible-image-lazy-load/

# Install dependencies
$ npm install

# Build (any of the below will do it)
$ npm run build
$ gulp

Gandul. Accessible Image Lazy loading
Jorge Moreno ā€” @alterebro

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
javascript (68,711)Ā 
accessibility (174)Ā 
images (165)Ā 
lazy-loading (65)Ā 
lazyload (32)Ā 
lazy (26)Ā 
accessible (25)Ā 

Find Open Source By Browsing 7,000 Topics Across 59 Categories

Advertising šŸ“¦Ā 10
All Projects
Application Programming Interfaces šŸ“¦Ā 124
Applications šŸ“¦Ā 192
Artificial Intelligence šŸ“¦Ā 78
Blockchain šŸ“¦Ā 73
Build Tools šŸ“¦Ā 113
Cloud Computing šŸ“¦Ā 80
Code Quality šŸ“¦Ā 28
Collaboration šŸ“¦Ā 32
Command Line Interface šŸ“¦Ā 49
Community šŸ“¦Ā 83
Companies šŸ“¦Ā 60
Compilers šŸ“¦Ā 63
Computer Science šŸ“¦Ā 80
Configuration Management šŸ“¦Ā 42
Content Management šŸ“¦Ā 175
Control Flow šŸ“¦Ā 213
Data Formats šŸ“¦Ā 78
Data Processing šŸ“¦Ā 276
Data Storage šŸ“¦Ā 135
Economics šŸ“¦Ā 64
Frameworks šŸ“¦Ā 215
Games šŸ“¦Ā 129
Graphics šŸ“¦Ā 110
Hardware šŸ“¦Ā 152
Integrated Development Environments šŸ“¦Ā 49
Learning Resources šŸ“¦Ā 166
Legal šŸ“¦Ā 29
Libraries šŸ“¦Ā 129
Lists Of Projects šŸ“¦Ā 22
Machine Learning šŸ“¦Ā 347
Mapping šŸ“¦Ā 64
Marketing šŸ“¦Ā 15
Mathematics šŸ“¦Ā 55
Media šŸ“¦Ā 239
Messaging šŸ“¦Ā 98
Networking šŸ“¦Ā 315
Operating Systems šŸ“¦Ā 89
Operations šŸ“¦Ā 121
Package Managers šŸ“¦Ā 55
Programming Languages šŸ“¦Ā 245
Runtime Environments šŸ“¦Ā 100
Science šŸ“¦Ā 42
Security šŸ“¦Ā 396
Social Media šŸ“¦Ā 27
Software Architecture šŸ“¦Ā 72
Software Development šŸ“¦Ā 72
Software Performance šŸ“¦Ā 58
Software Quality šŸ“¦Ā 133
Text Editors šŸ“¦Ā 49
Text Processing šŸ“¦Ā 136
User Interface šŸ“¦Ā 330
User Interface Components šŸ“¦Ā 514
Version Control šŸ“¦Ā 30
Virtualization šŸ“¦Ā 71
Web Browsers šŸ“¦Ā 42
Web Servers šŸ“¦Ā 26
Web User Interface šŸ“¦Ā 210