gandul. Accessible image lazy loading.
Intro / How to Use it / Image Attributes / Options / Examples
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.
<a href="https://placedog.net/320/180" class="gandul">Nice dog</a>
| Modern Browsers | Non-Modern Browsers | No Javascript Browsers |
|---|---|---|
| Browsers with JavaScript enabled and IntersectionObserver API support | Browsers with JavaScript enabled but no support for the IntersectionObserver API | Browsers or crawlers with no javascript support or disabled |
| Chrome, Firefox, Opera | IE, Safari <12.1, Edge <15 | |
| Image loaded only when it intersects with the defined bounds on the viewport (visible area of the browser) AKA Lazy loaded | Image loaded normally without lazy loading. It will start downloading when the DOM content is already loaded onto the page | A link with a reference to the image |
<img src="https://placedog.net/320/180" class="gandul" alt="Nice dog" /> | <img src="https://placedog.net/320/180" class="gandul" alt="Nice dog" /> | <a href="https://placedog.net/320/180" class="gandul">Nice dog</a> |
How to use it
1. Get the gandul script
You have multiple options to get gandul:
| Option | Step |
|---|---|
| CDN : UNPKG | unpkg.com/accessible-image-lazy-load |
| CDN : jsDelivr | cdn.jsdelivr.net/gh/alterebro/accessible-image-lazy-load/dist/gandul.min.js |
| NPM ( gandul module page ) | npm i accessible-image-lazy-load |
| Git repo clone | git clone https://github.com/alterebro/accessible-image-lazy-load.git |
| ZIP file Download | github.com/alterebro/accessible-image-lazy-load/archive/master.zip |
2. Get it working
Write on your HTML 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 :
<a href="resources/images/projects/gandul-accessible-image-lazy-loading.jpg" class="gandul">Gandul!</a>
<script src="https://unpkg.com/accessible-image-lazy-load"></script>
<script>gandul();</script>
| HTML Input | Gandul Output |
|---|---|
<a href="https://placedog.net/320/180" class="gandul">Nice dog</a> | <img src="https://placedog.net/320/180" class="gandul" alt="Nice dog" /> |
| Nice dog | |
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 on the use of different attributes :
Note: 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> attrs equivalence |
|---|---|
<a> inner text. | alt |
href | src |
data-href | src |
data-srcset | srcset |
data-sizes | sizes |
data-width | width |
Options
Some parameters can be send to the gandul function:
gandul(target, opts, action); // gandul function parameters
gandul('a.gandul', {
root : null,
rootMargin : "50px 0px 50px 0px",
threshold: 0
}, function() {}
); // gandul defaults
| Option | Description |
|---|---|
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 |
— opt : root | element used as viewport of the target. Default value is the brwoser viewport (null) |
— opt : 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"). |
— opt : 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) {
img.style.border = 'solid red 10px';
});