{"id":20322082,"url":"https://github.com/alterebro/accessible-image-lazy-load","last_synced_at":"2025-04-09T05:12:19.137Z","repository":{"id":34327921,"uuid":"176796140","full_name":"alterebro/accessible-image-lazy-load","owner":"alterebro","description":"😴 gandul! accessible lazy loading images","archived":false,"fork":false,"pushed_at":"2024-09-10T19:35:42.000Z","size":369,"stargazers_count":288,"open_issues_count":0,"forks_count":14,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-02T04:04:46.167Z","etag":null,"topics":["accessibility","accessible","images","lazy","lazy-loading","lazyload","lazyload-images"],"latest_commit_sha":null,"homepage":"https://codepen.io/alterebro/full/eozxwd","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alterebro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"alterebro","ko_fi":"alterebro","buy_me_a_coffee":"alterebro"}},"created_at":"2019-03-20T18:40:09.000Z","updated_at":"2024-12-13T06:00:32.000Z","dependencies_parsed_at":"2024-09-10T21:37:52.653Z","dependency_job_id":"c6f15285-8c93-4d00-bbcd-dd26c31b5366","html_url":"https://github.com/alterebro/accessible-image-lazy-load","commit_stats":{"total_commits":64,"total_committers":2,"mean_commits":32.0,"dds":0.25,"last_synced_commit":"a0c2853131b2d07fb4e88b5bd45b3187c9c7ee15"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alterebro%2Faccessible-image-lazy-load","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alterebro%2Faccessible-image-lazy-load/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alterebro%2Faccessible-image-lazy-load/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alterebro%2Faccessible-image-lazy-load/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alterebro","download_url":"https://codeload.github.com/alterebro/accessible-image-lazy-load/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247615417,"owners_count":20967183,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accessibility","accessible","images","lazy","lazy-loading","lazyload","lazyload-images"],"created_at":"2024-11-14T19:18:57.291Z","updated_at":"2025-04-09T05:12:19.116Z","avatar_url":"https://github.com/alterebro.png","language":"JavaScript","funding_links":["https://github.com/sponsors/alterebro","https://ko-fi.com/alterebro","https://buymeacoffee.com/alterebro"],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"gandul.png\" alt=\"gandul\" width=\"148\" /\u003e\n\n# **[gandul!](https://moro.es/projects/gandul-accessible-image-lazy-loading/)** 😴 (accessible-image-lazy-load)\n\n[![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)\n\n- [About gandul](#accessible-lazy-loading-images)\n- [How to use it](#how-to-use-it)\n- [Image attributes](#image-attributes)\n- [Options](#options)\n- [Development](#development)\n- [❐ \u0026nbsp; *Examples*](https://codepen.io/alterebro/full/eozxwd)\n- [❐ \u0026nbsp; *More Info*](https://moro.es/projects/gandul-accessible-image-lazy-loading/)\n\n---\n\n## Accessible lazy loading images\n\n**gandul** 😴 is a lightweight (\u003c2Kb) 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 `\u003cnoscript\u003e` tag. This could be hacky and verbose and the main issue with it is that alters the semantics of the original element.\n\nIn order to avoid that, **gandul** 😴 works by taking a common anchor hyperlink `\u003ca\u003e` as the data source of the image to be loaded and transforms it into a `\u003cimg\u003e` 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.\n\n#### Basic Example :\n\n```html\n\u003c!-- How your HTML will look like: --\u003e\n\u003ca href=\"http://picsum.photos/320/180\" class=\"gandul\"\u003eNice kitten\u003c/a\u003e\n\n\u003c!-- What the gandul script will output : --\u003e\n\u003cimg src=\"http://picsum.photos/320/180\" class=\"gandul\" alt=\"Nice kitten\" /\u003e\n```\n\n\u003ctable\u003e\n\u003cthead\u003e\n    \u003ctr\u003e  \n        \u003cth\u003eHTML Input\u003c/th\u003e\n        \u003cth\u003egandul 😴 Output\u003c/th\u003e\n    \u003c/tr\u003e  \n\u003c/thead\u003e\n\u003ctbody\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;a href=\"http://picsum.photos/320/180\" class=\"gandul\"\u0026gt;Nice kitten\u0026lt;/a\u0026gt;\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;img src=\"http://picsum.photos/320/180\" class=\"gandul\" alt=\"Nice kitten\" /\u0026gt;\u003c/code\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ca href=\"http://picsum.photos/320/180\" class=\"gandul\"\u003eNice kitten\u003c/a\u003e\u003c/td\u003e\n        \u003ctd\u003e\u003cimg src=\"http://picsum.photos/320/180\" class=\"gandul\" alt=\"Nice kitten\" /\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\n\n## How to use it\n\n#### 1. Download the script\n\nYou have multiple options to get gandul 😴 ( [gandul.min.js](dist/gandul.min.js) ):\n\n- Via [NPM](https://www.npmjs.com/package/accessible-image-lazy-load) : `npm i accessible-image-lazy-load`\n- By cloning the repository : `git clone https://github.com/alterebro/accessible-image-lazy-load.git`\n- By downloading the project : [Download ZIP](https://github.com/alterebro/accessible-image-lazy-load/archive/master.zip)\n- You can also include it from a CDN :\n    * **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)\n    * **UNPKG** : [`unpkg.com/accessible-image-lazy-load`](https://unpkg.com/accessible-image-lazy-load)\n\n#### 2. Get it working\n\nWrite an anchor hyperlink with the reference to your image and set the class gandul on it (`\u003ca class=\"gandul\"\u003e`). then, include and call the script :\n\n```html\n\u003c!-- How a gandul image reference looks like --\u003e\n\u003ca href=\"http://picsum.photos/200/200\" class=\"gandul\"\u003eNice kitten\u003c/a\u003e\n\n\u003c!-- Include and call the script --\u003e\n\u003cscript src=\"https://unpkg.com/accessible-image-lazy-load\"\u003e\u003c/script\u003e\n\u003cscript\u003egandul();\u003c/script\u003e\n```\n\n## Image Attributes\n\n**gandul** 😴 will take all the existing attributes on the `\u003ca\u003e` element and they will be passed to the newly created `\u003cimg\u003e` with a few peculiarities, as `\u003ca\u003e` 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:\n\n*In case you want to apply **gandul** to a different HTML element than a hyperlink (`\u003ca\u003e`) the image source will be taken from the `data-href` attribute*\n\n\n| \u0026lt;a\u0026gt; attributes  | \u0026lt;img\u0026gt; attributes equivalence  |\n|-----------------------|-------------|\n| Anchor hyperlink inner text. | `alt` \t|\n| `href`     \t\t\t| `src`  \t|\n| `data-href`     \t\t| `src`  \t|\n| `data-srcset`    \t\t| `srcset` \t|\n| `data-sizes`     \t\t| `sizes`  \t|\n| `data-width`     \t\t| `width`  \t|\n\n\n#### Fully responsive image example:\n\n```html\n\u003c!-- Write your hyperlink HTML as it follows : --\u003e\n\u003ca href=\"http://picsum.photos/800/400\"\n   data-srcset=\"http://picsum.photos/320/160 320w,\n             http://picsum.photos/480/240 480w,\n             http://picsum.photos/800/400 800w\"\n   data-sizes=\"(max-width: 320px) 280px, (max-width: 480px) 440px, 800px\"\n   class=\"gandul\"\u003eNice kitten\u003c/a\u003e\n\n\u003c!-- To get a responsive image output like this one: --\u003e\n\u003cimg src=\"http://picsum.photos/800/400\"\n\t srcset=\"http://picsum.photos/320/160 320w,\n             http://picsum.photos/480/240 480w,\n             http://picsum.photos/800/400 800w\"\n     sizes=\"(max-width: 320px) 280px, (max-width: 480px) 440px, 800px\"\n     class=\"gandul\"\n     alt=\"Nice kitten\" /\u003e\n\n```\n\n\n#### Setting just the width attribute of an image :\n\n```html\n\u003c!-- What you'll write: --\u003e\n\u003ca href=\"http://picsum.photos/800/400\" data-width=\"800\" class=\"gandul\"\u003eNice kitten\u003c/a\u003e\n\n\u003c!-- What you'll get : --\u003e\n\u003cimg src=\"http://picsum.photos/800/400\" width=\"800\" alt=\"Nice kitten\" /\u003e\n```\n\n\n#### Any other attributes :\n\nAny other attributes will remain as they are, which means that if you already set or you need on the `\u003cimg\u003e` an `id` or different `classes`, those will be passed through the **gandul** 😴 script :\n\n```html\n\u003c!-- input --\u003e\n\u003ca href=\"http://picsum.photos/800/400\" id=\"cat\" class=\"nice kitten gandul\"\u003eNice kitten\u003c/a\u003e\n\n\u003c!-- gandul output --\u003e\n\u003cimg src=\"http://picsum.photos/800/400\" id=\"cat\" class=\"nice kitten gandul\" alt=\"Nice kitten\" /\u003e\n```\n\n## Options\n\nSome parameters can be send to the **gandul** 😴 function:\n\n```javascript\ngandul(target, opts, action);\n```\n\n- **`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\"`\n- **`opts (@object)`** : an options object containing the fields used by the `IntersectionObserver` constructor\n    * `root` : element used as viewport of the target. Default value is the brwoser viewport (`null`)\n    * `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\"`).\n    * `threshold` : percentage of target visibility to trigger the action. Default is `0`.\n- **`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'`.\n\nThe 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:\n\n```javascript\ngandul('a.gandul-hyperlink', { threshold: .5 }, function(img) {\n    img.style.border = 'solid red 10px';\n});\n```\n\n---\n\n## Development\n\n```sh\n# Clone the repo\n$ git clone https://github.com/alterebro/accessible-image-lazy-load.git\n$ cd accessible-image-lazy-load/\n\n# Install dependencies\n$ npm install\n\n# Build (any of the below will do it)\n$ npm run build\n$ gulp\n```\n\n---\n\n**[Gandul. Accessible Image Lazy loading](https://moro.es/projects/gandul-accessible-image-lazy-loading/)**\u003cbr\u003e*Jorge Moreno — [@alterebro](https://twitter.com/alterebro)*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falterebro%2Faccessible-image-lazy-load","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falterebro%2Faccessible-image-lazy-load","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falterebro%2Faccessible-image-lazy-load/lists"}