{"id":15988220,"url":"https://github.com/erikyo/fast-lazyload","last_synced_at":"2025-02-23T07:28:02.485Z","repository":{"id":229932351,"uuid":"777904326","full_name":"erikyo/fast-lazyload","owner":"erikyo","description":null,"archived":false,"fork":false,"pushed_at":"2024-03-27T08:09:38.000Z","size":111,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-04T16:44:37.063Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/erikyo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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}},"created_at":"2024-03-26T18:08:31.000Z","updated_at":"2024-03-27T01:19:44.000Z","dependencies_parsed_at":"2024-11-09T13:37:36.784Z","dependency_job_id":"424ab66c-7334-4213-8fe3-e326a5f3481a","html_url":"https://github.com/erikyo/fast-lazyload","commit_stats":{"total_commits":19,"total_committers":1,"mean_commits":19.0,"dds":0.0,"last_synced_commit":"2158ab65674b407680e0e56ae1250b322af951cc"},"previous_names":["erikyo/fast-lazyload"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erikyo%2Ffast-lazyload","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erikyo%2Ffast-lazyload/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erikyo%2Ffast-lazyload/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erikyo%2Ffast-lazyload/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/erikyo","download_url":"https://codeload.github.com/erikyo/fast-lazyload/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240283458,"owners_count":19776875,"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":[],"created_at":"2024-10-08T04:02:10.601Z","updated_at":"2025-02-23T07:28:02.435Z","avatar_url":"https://github.com/erikyo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fast Lazy Load\n[![](https://img.shields.io/npm/v/fast-lazyload.svg?label=npm%20version)](https://www.npmjs.com/package/fast-lazyload)\n[![](https://img.shields.io/npm/l/fast-lazyload)](https://github.com/erikyo/fast-lazyload?tab=GPL-3.0-1-ov-file#readme)\n\n## Why?\nWhile lazy loading is hailed as a game-changer in optimizing web performance, not all implementations are created equal.\nTraditional lazy loaders may inadvertently delay crucial content, leading to detrimental effects on your site's Largest Contentful Paint (LCP).\nRead more about [this](https://web.dev/articles/lazy-loading-images) and about the [Largest Contentful Paint (LCP)](https://web.dev/lcp/).\n\n## How It Works\nThe script operates at the core of your webpage's creation process, thanks to the vigilant watch of the Mutation Observer API.\nIt meticulously observes every addition to the DOM, ensuring that when an element, be it an image or video, is appended, it comes complete with its source set.\nBy sidestepping proxies and preemptively loading content with its true source, we safeguard your site's Largest Contentful Paint (LCP) metrics.\nThis proactive approach not only optimizes loading times but also guarantees a seamless user experience from the moment your page springs to life.\n\n## Features\n\n- Lazily loads images, videos, and background images.\n- Intersection Observer to efficiently detect when elements enter the viewport.\n- Set the fetchpriority to `high` for the images and videos inside the viewport automatically ([ref.](https://web.dev/articles/optimize-lcp?utm_source=lighthouse\u0026utm_medium=lr#optimize-resource-priority)).\n- Employs Mutation Observer to dynamically handle changes in the DOM, ensuring newly added lazy elements are also properly observed.\n- Provides a fallback mechanism for browsers that do not support the required APIs.\n\n## Usage\n\n### Installation\n\n1. Include **the script at the beginning of the `\u003cbody\u003e` tag in your HTML document**.\n2. Ensure the script is added before any content that requires lazy loading.\n\n```html\n\u003cbody\u003e\n  \u003cscript src=\"https://www.unpkg.com/fast-lazyload\"\u003e\u003c/script\u003e\n  ...\n\u003c/body\u003e\n```\n\n## The Markup changes required\n\nTo get started, add the `data-lazy` attribute to any element you want to lazy load.\nThe library will check for the existence of a style attribute with a background image.\nIf it does not exist, it will assume the element that requires lazy loading adding or replacing the src.\n\n```html\n\u003c!-- Image --\u003e\n\u003cimg src=\"proxy.jpg\" data-lazy=\"original.png\" data-srcset=\"[original srcset]\" width=\"960\" height=\"540\" /\u003e\n\u003c!-- Background image --\u003e\n\u003cdiv style=\"background-image:url(proxy.jpg); width: 960px; height: 540px\" data-lazy=\"original.png\"\u003e\u003c/div\u003e\n\u003c!-- Video --\u003e\n\u003cvideo autoplay muted data-lazy=\"original.mp4\" style=\"background-image:url(proxy.jpg); width: 960px; height: 540px\"\u003e\u003c/video\u003e\n\u003c!-- Audio --\u003e\n\u003caudio data-lazy=\"original.mp3\"\u003e\u003c/audio\u003e\n\u003c!-- Script --\u003e\n\u003cscript data-lazy=\"myHeavyScript.js\"\u003e\u003c/script\u003e\n```\n\n## User Configurable Options\n\nIf needed, you have the flexibility to customize the lazy loading behavior by setting the `lazyloadOptions` object in the `window` object before the document is loaded. This allows you to override the default options to tailor lazy loading according to your specific requirements.\n\n### Example:\n\n```javascript\nwindow.lazyloadOptions = {\n    loading: 'my-lazy-loading',\n    failed: 'my-lazy-failed',\n    on: 'my-lazy',\n    loaded: 'my-lazy-loaded',\n    attribute: 'data-lazy'\n};\n```\n\n### Default Options:\n\nIf no custom options are provided, the script will fall back to the default options:\n\n```javascript\nconst Options = {\n    loading: 'lazy-loading',\n    failed: 'lazy-failed',\n    on: 'lazy',\n    loaded: 'lazy-loaded',\n    attribute: 'data-lazy'\n};\n```\n\n### Animating Lazy Loaded Items\n\nIntegrating animations with lazy loaded items can significantly enhance the visual appeal and user engagement of your website.\n\n- When an element enters the viewport, classes `lazy` and `loading` are added to indicate visibility and loading.\n- Upon successful loading of source, class `Options.loaded` is added, and `Options.loading` is removed and the data-lazy attribute is removed too.\n- If loading fails, class `Options.failed` is added.\n- When an element leaves the viewport, the classes `Options.on` and `Options.loading` are removed.\n\n\n#### CSS examples:\n\n```css\nimg.lazy {\n    opacity: 0;\n    transition: opacity 0.5s ease-in-out;\n}\n\nimg.lazy.loaded {\n    opacity: 1;\n    animation: blink 0.5s ease-in-out;\n}\n\nvideo.lazy.loading {\n  background-image: url(\"spinner.gif\");\n}\n\naudio.lazy.failed {\n  background-image: url(\"404.jpg\");\n}\n```\n\n### Compatibility\n\n- The script is designed to work in modern browsers that support both Intersection Observer and Mutation Observer APIs.\n- A fallback mechanism is provided for browsers that do not support Intersection Observer, ensuring basic functionality across a wide range of browsers.\n\n## What the script does after being loaded\n\n1. The script initially queries for all elements with the `data-lazy` attribute, which are considered lazy-loadable elements.\n2. If the browser supports Intersection Observer and Mutation Observer, it creates instances of both.\n3. Intersection Observer is used to monitor lazy-loadable elements and trigger loading when they enter the viewport.\n4. Mutation Observer watches for changes in the DOM, ensuring any dynamically added lazy elements are also properly observed.\n5. For browsers lacking Intersection Observer support, a fallback mechanism directly loads all lazy elements.\n\n## Caveats\n\n- The script relies on the availability of Intersection Observer and Mutation Observer APIs. Ensure compatibility with your target browsers.\n- It's essential to use the `data-lazy` attribute on elements you intend to load lazily.\n- Background image should be a style attribute and should be set (e.g. `background-image:url(proxy.jpg);`) otherwise will be considered as a src replacement\n\n## Contributing\n\nIf you encounter any issues or have suggestions for improvements, feel free to contribute by submitting a pull request or opening an issue on the GitHub repository.\n\n## License\n\nThis script is licensed under the [MIT License](https://opensource.org/licenses/MIT). You are free to modify and distribute it as per the terms of the license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferikyo%2Ffast-lazyload","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ferikyo%2Ffast-lazyload","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferikyo%2Ffast-lazyload/lists"}