{"id":13547579,"url":"https://github.com/transitive-bullshit/lqip-modern","last_synced_at":"2025-04-14T08:56:36.209Z","repository":{"id":37092743,"uuid":"289677886","full_name":"transitive-bullshit/lqip-modern","owner":"transitive-bullshit","description":"Modern approach to Low Quality Image Placeholders (LQIP) using webp and sharp.","archived":false,"fork":false,"pushed_at":"2024-11-08T02:23:59.000Z","size":6897,"stargazers_count":340,"open_issues_count":4,"forks_count":10,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-07T02:07:56.840Z","etag":null,"topics":["images","lqip","progressive-image","webp"],"latest_commit_sha":null,"homepage":"https://transitive-bullshit.github.io/lqip-modern/","language":"JavaScript","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/transitive-bullshit.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":".github/funding.yml","license":null,"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":["transitive-bullshit"]}},"created_at":"2020-08-23T12:05:09.000Z","updated_at":"2025-04-04T14:03:35.000Z","dependencies_parsed_at":"2024-06-18T15:19:16.677Z","dependency_job_id":"ea2416cb-7f0d-4af7-a011-5bf1ae75ec4b","html_url":"https://github.com/transitive-bullshit/lqip-modern","commit_stats":{"total_commits":38,"total_committers":2,"mean_commits":19.0,"dds":0.02631578947368418,"last_synced_commit":"ce00f2f36c7b078e7347eb705f47306dce06a9ee"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transitive-bullshit%2Flqip-modern","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transitive-bullshit%2Flqip-modern/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transitive-bullshit%2Flqip-modern/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transitive-bullshit%2Flqip-modern/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/transitive-bullshit","download_url":"https://codeload.github.com/transitive-bullshit/lqip-modern/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248852112,"owners_count":21171839,"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":["images","lqip","progressive-image","webp"],"created_at":"2024-08-01T12:00:58.292Z","updated_at":"2025-04-14T08:56:36.190Z","avatar_url":"https://github.com/transitive-bullshit.png","language":"JavaScript","funding_links":["https://github.com/sponsors/transitive-bullshit"],"categories":["JavaScript"],"sub_categories":[],"readme":"# lqip-modern\n\n\u003e Modern approach to Low Quality Image Placeholders (LQIP) using `webp` and `sharp`. ([demo](https://transitive-bullshit.github.io/lqip-modern/))\n\n[![NPM](https://img.shields.io/npm/v/lqip-modern.svg)](https://www.npmjs.com/package/lqip-modern) [![Build Status](https://github.com/transitive-bullshit/lqip-modern/actions/workflows/test.yml/badge.svg)](https://github.com/transitive-bullshit/lqip-modern/actions/workflows/test.yml) [![Prettier Code Formatting](https://img.shields.io/badge/code_style-prettier-brightgreen.svg)](https://prettier.io)\n\nThis approach is **extremely fast** and produces **much smaller outputs** than alternatives.\n\n## Examples\n\nCheck out the [demo](https://transitive-bullshit.github.io/lqip-modern/) for more examples and details.\n\n[![](https://raw.githubusercontent.com/transitive-bullshit/lqip-modern/master/preview.jpg)](https://transitive-bullshit.github.io/lqip-modern/)\n\n## How It Works\n\nThis package uses a very similar LQIP approach to the one used by [Medium](https://medium.com/).\n\nWe use `sharp` to resize input images to a max dimension of `16px` and output `webp` (default) or `jpeg` images with an encoding `quality` set to 20. The max dimension is a single, simple variable to tradeoff between encoded image size and visual fidelity.\n\nThis results in very efficient placeholder images that have noticeable artifacts due to the low quality encoding. These artifacts are then hidden in the browser using a simple blur filter.\n\n```css\n.placeholder {\n  filter: blur(20px);\n  transform: scale(1.1);\n}\n```\n\nNote that Medium uses this scale transform on its placeholder images for two reasons:\n\n- Hide the [artifacts around the edges](http://volkerotto.net/2014/07/03/css-background-image-blur-without-blury-edges/) of the blurred images.\n- Provide an aesthetically pleasing feeling of zooming into the original image once it's loaded.\n\nAn alternative to using this `blur` + `transform` technique is to use a CSS [backdrop-filter](https://css-tricks.com/almanac/properties/b/backdrop-filter/). This technique has less [cross-browser support](https://caniuse.com/#search=backdrop-filter), but it produces clean blurred preview images without the need to transform the placeholder.\n\n```css\n.placeholder::after {\n  content: '';\n  position: absolute;\n  top: 0;\n  left: 0;\n  right: 0;\n  bottom: 0;\n  backdrop-filter: blur(20px);\n  pointer-events: none;\n}\n```\n\n## Install\n\n```bash\nnpm install --save lqip-modern\n## or\nyarn add lqip-modern\n## or\npnpm add lqip-modern\n```\n\n## Usage\n\n```js\nconst lqip = require('lqip-modern')\nconst result = await lqip('fixtures/brooklyn.jpg')\n```\n\nwhich outputs\n\n```js\n{\n  content: \u003cBuffer\u003e,\n  metadata: {\n    originalWidth: 1400,\n    originalHeight: 350,\n    width: 16,\n    height: 4,\n    type: 'webp',\n    dataURIBase64: 'data:image/webp;base64,UklGRkIAAABXRUJQVlA4IDYAAADQAQCdASoQAAQABUB8JYgCdADjazMu8AD+flCYsVr2GH6CLYVog1jhRLpBUIu8UmqhGnoAAAA='\n  }\n}\n```\n\nIf you pass an array of inputs, the result will be an array of outputs.\n\nThe format of the output is as close to [sqip](https://github.com/axe312ger/sqip) as possible for easy comparison.\n\n## API\n\n\u003c!-- Generated by documentation.js. Update this documentation by updating the source code. --\u003e\n\n### [lqipModern](https://git@github.com/transitive-bullshit/lqip-modern/blob/c3e6abe7ccb77416b34d3c5b8cf37c473327ae0d/index.js#L17-L27)\n\n- `input` **([Buffer](https://nodejs.org/api/buffer.html) \\| [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \\| [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)\u0026lt;[Buffer](https://nodejs.org/api/buffer.html)\u003e | [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)\u0026lt;[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)\u003e)** Either an array of image inputs or a single image input.\n  Each image input may either be a `Buffer` containing raw image data, or a `string` containing the filesystem path to a supported image type.\n- `opts` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Optional configuration options.\n  - `opts.concurrency` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** Concurrency when processing an array of input images. (optional, default `4`)\n  - `opts.outputFormat` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Output format to use; either `webp` or `jpeg` (passing `jpg` is the same as passing `jpeg`). (optional, default `'webp'`)\n  - `opts.outputOptions` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Output options passed to either `sharp.webp` or `sharp.jpeg` dependent on `opts.outputFormat`.\n  - `opts.resize` **([number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) \\| [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)\u0026lt;any\u003e)?** Options to pass to `sharp.resize`. Defaults to resizing inputs to a max dimension of `16`, with the other dimension being calculated to maintain aspect ratio. If you want more control, you can pass an array of args here which will be forwarded to `sharp.resize`.\n\n## Compatibility\n\nWebp is supported by [98% of browsers](https://caniuse.com/#feat=webp) and produces significantly smaller results.\n\nIf you need 100% browser support, then I recommend that you use the `jpeg` output format or [sqip](https://github.com/axe312ger/sqip).\n\nIn the future, I'd love to experiment with outputting `jpeg` at full quality and then compressing the results with [mozjpeg](https://github.com/imagemin/mozjpeg-bin) at 20% quality.\n\n## Comparison\n\n| Approach        | format | Width    | Avg Encode Speed | Avg Size |\n| --------------- | ------ | -------- | ---------------- | -------- |\n| lqip-modern 🔥  | webp   | 16px     | 0.011s           | 152 B    |\n| lqip-modern     | jpeg   | 16px     | 0.003s           | 274 B    |\n| lqip-modern     | webp   | 8px      | 0.014s           | 129 B    |\n| lqip-modern     | jpeg   | 8px      | 0.003s           | 244 B    |\n| lqip-modern     | webp   | 32px     | 0.013s           | 257 B    |\n| lqip-modern     | jpeg   | 32px     | 0.002s           | 347 B    |\n| lqip (original) | jpeg   | 10px     | 0.395s           | 887 B    |\n| lqip-custom     | jpeg   | 32px     | 0.040s           | 545 B    |\n| sqip (default)  | svg    | original | 1.468s           | 509 B    |\n\nCheck out the [demo](https://transitive-bullshit.github.io/lqip-modern/) for full results.\n\n_Generated with a [fork of sqip's excellent comparison benchmark](https://github.com/transitive-bullshit/sqip/tree/feature/lqip-modern/demo)._\n\n## Related\n\n- [lqip](https://github.com/zouhir/lqip) - Original Low Quality Image Placeholders (LQIP) module.\n- [sqip](https://github.com/axe312ger/sqip) - Really solid SVG-based LQIP alternative.\n  - See their comprehensive [comparison](https://axe312ger.github.io/sqip/) of LQIP techniques.\n  - The biggest disadvantage of this approach is that it's ~10-100x slower to compute these images.\n- [blurhash](https://github.com/woltapp/blurhash) - Really nice, compact placeholder images.\n  - Requires non-native client-side decoding which makes it awkward and slow for browser usage.\n  - Encoding speed is pretty slow (on par with sqip).\n  - Under the hood, the `webp` format performs a similar set of transforms as the one used by blurhash.\n\n## License\n\nMIT © [Travis Fischer](https://github.com/transitive-bullshit)\n\nSupport my OSS work by \u003ca href=\"https://twitter.com/transitive_bs\"\u003efollowing me on twitter \u003cimg src=\"https://storage.googleapis.com/saasify-assets/twitter-logo.svg\" alt=\"twitter\" height=\"24px\" align=\"center\"\u003e\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftransitive-bullshit%2Flqip-modern","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftransitive-bullshit%2Flqip-modern","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftransitive-bullshit%2Flqip-modern/lists"}