{"id":18567989,"url":"https://github.com/willybrauner/lazy-image","last_synced_at":"2025-04-10T05:32:43.822Z","repository":{"id":40562677,"uuid":"397524518","full_name":"willybrauner/lazy-image","owner":"willybrauner","description":"💤  A zero dependency lazy and responsive image management for image and background-image","archived":false,"fork":false,"pushed_at":"2022-12-13T11:28:51.000Z","size":673,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-24T16:47:25.249Z","etag":null,"topics":["background-image","image","lazyload","lib","library","react","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/willybrauner.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-08-18T08:16:21.000Z","updated_at":"2024-03-14T14:18:11.000Z","dependencies_parsed_at":"2023-01-28T11:40:11.876Z","dependency_job_id":null,"html_url":"https://github.com/willybrauner/lazy-image","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willybrauner%2Flazy-image","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willybrauner%2Flazy-image/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willybrauner%2Flazy-image/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willybrauner%2Flazy-image/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/willybrauner","download_url":"https://codeload.github.com/willybrauner/lazy-image/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248163265,"owners_count":21057896,"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":["background-image","image","lazyload","lib","library","react","typescript"],"created_at":"2024-11-06T22:28:22.704Z","updated_at":"2025-04-10T05:32:43.146Z","avatar_url":"https://github.com/willybrauner.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @wbe/lazy-image\n\nA zero dependency lazy and responsive image management for image and background-image.\nReact wrapper component using `lazy-image` is available too.\nBecause the native `loading=\"lazy\"` is not supported on all browsers for now, this library used intersection-observer to detect when the image is visible in the viewport.\n\n![](https://img.shields.io/npm/v/@wbe/lazy-image/latest.svg)\n![](https://img.shields.io/bundlephobia/minzip/@wbe/lazy-image.svg)\n![](https://img.shields.io/npm/dt/@wbe/lazy-image.svg)\n![](https://img.shields.io/npm/l/@wbe/lazy-image.svg)\n\n## Summary\n\n- [Vanilla LazyImage](#LazyImage)\n- [React LazyImage](#ReactLazyImage)\n\n## Installation\n\n```shell script\n$ npm install -s @wbe/lazy-image\n```\n\n## \u003ca name=\"LazyImage\"\u003e\u003c/a\u003eLazyImage\n\n### Lazyload a group of images\n\nLazy image is build to manage lazyloading and responsive via native srcset.\n\nHTML template:\n\n```html\n\u003cimg alt=\"image\" data-srcset=\"img-1.jpg 360w, img-2.jpg 768w\" /\u003e\n\u003cimg alt=\"image-2\" data-srcset=\"img-1-2.jpg 360w, img-2-2.jpg 768w\" /\u003e\n```\n\n```js\nimport { LazyImage } from \"@wbe/lazy-image\"\n\nconst image = new LazyImage()\n// start to listen\nimage.start()\n// stop to listen\nimage.stop()\n// update listeners\nimage.update()\n```\n\nWhen image is appear in viewport, data-srcset value is injected in srcset attribute.\n\n```html\n\u003cimg\n  alt=\"image\"\n  class=\"lazyloaded\"\n  srcset=\"img-1.jpg 360w, img-2.jpg 768w\"\n  data-srcset=\"img-1.jpg 360w, img-2.jpg 768w\"\n/\u003e\n\u003c!-- ... --\u003e\n```\n\n### Lazyload a specific image\n\n`LazyImage()` can lazyload specific image only.\n\n```html\n\u003cimg alt=\"image\" id=\"singleImage\" srcset=\"img-360.jpg 360w, img-768.jpg 768w\" /\u003e\n```\n\n```js\nconst singleImage = new LazyImage({\n  $element: document.getElementById(\"singleImage\"),\n})\n```\n\n### Parameters\n\nAll parameters are optional.\n\n| param             | type                       | description                                                                         | default value   |\n| ----------------- | -------------------------- | ----------------------------------------------------------------------------------- | --------------- |\n| `$root`           | `string`                   | parent DOM element who contains images to lazyload                                  | `document.body` |\n| `$element`        | `HTMLElement`              | lazyLoad a specific DOM image element                                               | /               |\n| `src`             | `string`                   | if $element is set, define an image src to lazyload                                 | /               |\n| `srcset`          | `string`                   | if $element is set, define an image srcset to lazyload                              | /               |\n| `lazyCallback`    | `(state)=\u003e void`           | callback executed when lazy state change (`lazyload`, `lazyloading` , `lazyloaded`) | `() =\u003e {}`      |\n| `observerOptions` | `IntersectionObserverInit` | mutation observer options                                                           | `{}`            |\n\n## LazyBackgroundImage\n\n`LazyBackgroundImage()` set the appropriate image URL from srcset, in CSS background-image url of specific div.\nThis appropriate image URL depends of element width.\n\n### Lazyload a group of background-images\n\n```html\n\u003cdiv data-background-srcset=\"img-1.jpg 360w, img-2.jpg 768w\" /\u003e\n```\n\n```js\nimport { LazyBackgroundImage } from \"@wbe/lazy-image\"\n\nconst backgroundImage = new LazyBackgroundImage()\nbackgroundImage.start()\n```\n\nWhen DOM element appear in viewport, and element width is less than 360px:\n\n```html\n\u003cdiv\n  class=\"lazyloaded\"\n  data-background-srcset=\"img-1.jpg 360w, img-2.jpg 768w\"\n  style=\"background-image: url('img-1.jpg')\"\n/\u003e\n```\n\n### Lazyload a specific background-image\n\n`LazyBackgroundImage()` can lazyload specific css image only.\n\n```html\n\u003cdiv id=\"single\" data-background-srcset=\"img-1.jpg 360w, img-2.jpg 768w\" /\u003e\n```\n\n```js\nimport { LazyBackgroundImage } from \"@wbe/lazy-image\"\n\nconst singleBackgroundImage = new LazyBackgroundImage({\n  $element: document.getElementById(\"single\"),\n})\n// start to listen\nsingleBackgroundImage.start()\n// stop to listen\nsingleBackgroundImage.stop()\n// update listeners\nsingleBackgroundImage.update()\n```\n\nOr don't specify image srcset in DOM but, directly as function param.\n\n```html\n\u003cdiv id=\"single\" /\u003e\n```\n\n```js\nimport { LazyBackgroundImage } from \"@wbe/lazy-image\"\n\nconst singleBackgroundImage = LazyBackgroundImage({\n  $element: document.getElementById(\"single\"),\n  srcset: \"img-1.jpg 360w, img-2.jpg 768w\",\n})\nsingleBackgroundImage.start()\n```\n\n## Parameters\n\nAll parameters are optional.\n\n| param             | type                       | description                                                                                                                                                            | default value   |\n| ----------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |\n| `$root`           | `string`                   | parent DOM element who contains images to lazyload                                                                                                                     | `document.body` |\n| `$element`        | `HTMLElement`              | lazyLoad a specific DOM image element                                                                                                                                  | /               |\n| `srcset`          | `string`                   | if $element is set, define an image srcset to lazyload                                                                                                                 | /               |\n| `additonalUrl`    | `string`                   | add a second css URL behind the first one                                                                                                                              | /               |\n| `lazyCallback`    | `(state)=\u003e void`           | callback executed when lazy state change (`lazyload`, `lazyloading` , `lazyloaded`)                                                                                    | `() =\u003e {}`      |\n| `observerOptions` | `IntersectionObserverInit` | mutation observer options                                                                                                                                              | /               |\n| `bigQuality`      | `boolean`                  | will returns 2 steps bigger image (ex: if 360, 768, 1024 img are available, and DOM element width is less than 360, the function will return 768 img instead the 360 ) | `false`         |\n\n## \u003ca name=\"ReactLazyImage\"\u003e\u003c/a\u003eReact LazyImage\n\nReact image component with lazyloading management.\n\n## `\u003cImage /\u003e` component\n\n```js\nimport { Image } from \"@wbe/lazy-image\"\n```\n\n### `src` props\n\nBe sure you set appropriated css image width and height.\n\n```js\n\u003cImage src={`https://image-url`} alt={\"src image\"} /\u003e\n```\n\nWill return this HTML before lazyload:\n\n```html\n\u003cimg\n  class=\"Image lazyload\"\n  alt=\"src image\"\n  src=\"data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==\"\n  data-src=\"https://image-url\"\n/\u003e\n```\n\nand after lazyload:\n\n```html\n\u003cimg\n  class=\"Image lazyloaded\"\n  alt=\"src image\"\n  src=\"https://image-url\"\n  data-src=\"https://image-url\"\n/\u003e\n```\n\n### `srcset` props\n\n```js\n\u003cImage srcset={`https://image-url 360w, https://image-url-2 768w`} alt={\"srcset image\"} /\u003e\n```\n\n### `data` props\n\nWill generate an appropriated srcset string.\n\n```js\nconst data = [\n  {\n    url: \"https://url\",\n    width: 600,\n    height: 400,\n  },\n  {\n    url: \"https://url-2\",\n    width: 1000,\n    height: 800,\n  },\n]\n\n;\u003cImage data={data} alt={\"srcset image\"} /\u003e\n```\n\n### `srcPlaceholder` props\n\nAllow to display specific low quality image before lazyloading src image.\n\n```js\n\u003cImage srcPlaceholder={`https://low-quality-image-url`} src={`https://image-url`} alt={\"\"} /\u003e\n```\n\n### Props list\n\n```ts\ninterface IProps {\n  // image to display before lazyload\n  // default is lightest base64 transparent image\n  srcPlaceholder?: string\n\n  // src URL to lazyload\n  src?: string\n\n  // srcset URL to lazyload\n  srcset?: string\n\n  // list of images with dimension used to build srcset attr\n  data?: TImageData[]\n\n  // callback when lazyload state change (lazyload | lazyloading | lazyloaded)\n  lazyCallback?: (lazyState: TLazy) =\u003e void\n\n  // intersection observer options\n  observerOptions?: IntersectionObserverInit\n\n  // alt attr and aria html\n  alt: string\n  ariaLabel?: string\n\n  // class name added on root element\n  className?: string\n\n  // style attrs\n  style?: CSSProperties\n  width?: number | string\n  height?: number | string\n}\n```\n\n## `\u003cBackgroundImage /\u003e`\n\nWorks this the same API than `\u003cImage /\u003e` component.\n\nBefore lazyload:\n\n```html\n\u003cdiv\n  class=\"BackgroundImage lazyload\"\n  style=\"background-image: url('data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==')\"\n  data-background-srcset=\"img-1.jpg 360w, img-2.jpg 768w\"\n/\u003e\n```\n\nAfter lazyload:\n\n```html\n\u003cdiv\n  class=\"BackgroundImage lazyloaded\"\n  style=\"background-image: url('img-1.jpg')\"\n  data-background-srcset=\"img-1.jpg 360w, img-2.jpg 768w\"\n/\u003e\n```\n\n## `\u003cPlaceholder /\u003e` wrapper component\n\nImage component comes with `\u003cPlaceholder /\u003e` parent component\nused to display a placeholder behind Image. This process is particulary useful\nwhen image is lazyloading. It allows to not preload all 1px height images in pages\non page load but really waiting the image was shown in viewport to lazyload it.\n\nExample with `\u003cImage /\u003e`:\n\n```js\n\u003cPlaceholder\u003e\n    \u003cImage\n      src={`https://image-url`}\n      width={600}\n      height={400}\n      alt={\"with placeholder\"}\n    /\u003e\n\u003c/Placeholder\u003e\n```\n\nExample with `\u003cBackgroundImage /\u003e`:\n\n```js\n\u003cPlaceholder\u003e\n    \u003cBackgroundImage\n      src={`https://image-url`}\n      // or srcset={`https://image-url 360w, https://image-url 768w`}\n      width={600}\n      height={400}\n      alt={\"with placeholder\"}\n    /\u003e\n\u003c/Placeholder\u003e\n```\n\n`\u003cPlaceholder /\u003e` get children Image ratio to calculate its placeholder height.\nIt's possible to specify an arbitrary ratio who will override image dimension\n\n```js\n\u003cPlaceholder ratio={3/4}\u003e\n    \u003cImage\n      src={`https://image-url`}\n      alt={\"with placeholder\"}\n    /\u003e\n\u003c/Placeholder\u003e\n```\n\n## Props list\n\n```ts\ninterface IProps {\n  // Image component\n  children: ReactNode\n\n  // by default, ratio is calc from children image data dimension.\n  // set ratio override native image ratio\n  ratio?: number\n\n  // shortcut to style wrapper background color\n  backgroundColor?: string\n\n  // add style to each dom element\n  style?: {\n    root?: CSSProperties\n    wrapper?: CSSProperties\n    img?: CSSProperties\n  }\n\n  // class name added on root element\n  className?: string\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwillybrauner%2Flazy-image","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwillybrauner%2Flazy-image","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwillybrauner%2Flazy-image/lists"}