Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/alterebro/accessible-image-lazy-load

😴 gandul! accessible lazy loading images
https://github.com/alterebro/accessible-image-lazy-load

accessibility accessible images lazy lazy-loading lazyload lazyload-images

Last synced: 6 days ago
JSON representation

😴 gandul! accessible lazy loading images

Host: GitHub
URL: https://github.com/alterebro/accessible-image-lazy-load
Owner: alterebro
License: mit
Created: 2019-03-20T18:40:09.000Z (almost 6 years ago)
Default Branch: master
Last Pushed: 2024-09-10T19:35:42.000Z (5 months ago)
Last Synced: 2025-01-11T21:05:45.574Z (14 days ago)
Topics: accessibility, accessible, images, lazy, lazy-loading, lazyload, lazyload-images
Language: JavaScript
Homepage: https://codepen.io/alterebro/full/eozxwd
Size: 360 KB
Stars: 288
Watchers: 6
Forks: 15
Open Issues: 0
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE

Awesome Lists containing this project

README

        

# **[gandul!](https://moro.es/projects/gandul-accessible-image-lazy-loading/)** 😴 (accessible-image-lazy-load)

[![MIT license](https://img.shields.io/github/license/alterebro/accessible-image-lazy-load.svg)](http://opensource.org/licenses/MIT) [![NPM Version](https://img.shields.io/npm/v/accessible-image-lazy-load.svg)](https://www.npmjs.com/package/accessible-image-lazy-load) [![File Size](https://img.shields.io/github/size/alterebro/accessible-image-lazy-load/dist/gandul.min.js.svg)](https://github.com/alterebro/accessible-image-lazy-load/blob/master/dist/gandul.min.js) [![Twitter](https://img.shields.io/twitter/follow/alterebro.svg)](https://twitter.com/alterebro)

- [About gandul](#accessible-lazy-loading-images)

- [How to use it](#how-to-use-it)

- [Image attributes](#image-attributes)

- [Options](#options)

- [Development](#development)

- [❐   *Examples*](https://codepen.io/alterebro/full/eozxwd)

- [❐   *More Info*](https://moro.es/projects/gandul-accessible-image-lazy-loading/)

---

## 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 `` 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 `` as the data source of the image to be loaded and transforms it into a `` 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 :

```html

Nice kitten



```

      

        HTML Input

        gandul 😴 Output

      

    

        <a href="http://picsum.photos/320/180" class="gandul">Nice kitten</a>

        <img src="http://picsum.photos/320/180" class="gandul" alt="Nice kitten" />

    

    

        Nice kitten

        

    

## How to use it

#### 1. Download the script

You have multiple options to get gandul 😴 ( [gandul.min.js](dist/gandul.min.js) ):

- Via [NPM](https://www.npmjs.com/package/accessible-image-lazy-load) : `npm i accessible-image-lazy-load`

- By cloning the repository : `git clone https://github.com/alterebro/accessible-image-lazy-load.git`

- By downloading the project : [Download ZIP](https://github.com/alterebro/accessible-image-lazy-load/archive/master.zip)

- You can also include it from a CDN :

    * **jsDelivr** : [`cdn.jsdelivr.net/gh/alterebro/accessible-image-lazy-load/dist/gandul.min.js`](https://cdn.jsdelivr.net/gh/alterebro/accessible-image-lazy-load/dist/gandul.min.js)

    * **UNPKG** : [`unpkg.com/accessible-image-lazy-load`](https://unpkg.com/accessible-image-lazy-load)

#### 2. Get it working

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


```html

Nice kitten

gandul();

```

## Image Attributes

**gandul** 😴 will take all the existing attributes on the `` element and they will be passed to the newly created `` with a few peculiarities, as `` 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 (``) 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:

```html

Nice kitten



```

#### Setting just the width attribute of an image :

```html

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 `` an `id` or different `classes`, those will be passed through the **gandul** 😴 script :

```html

Nice kitten



```

## Options

Some parameters can be send to the **gandul** 😴 function:

```javascript

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:

```javascript

gandul('a.gandul-hyperlink', { threshold: .5 }, function(img) {

    img.style.border = 'solid red 10px';

});

```

---

## Development

```sh

# Clone the repo

$ git clone https://github.com/alterebro/accessible-image-lazy-load.git

$ 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](https://moro.es/projects/gandul-accessible-image-lazy-loading/)**
*Jorge Moreno — [@alterebro](https://twitter.com/alterebro)*