@alfred.westerveld/css-lqip

Low-quality image placeholders (LQIP) in two flavours from one image:

• CSS-gradient — a 20-bit --lqip integer decoded entirely in pure CSS (after Lean Rada). Zero JS, zero extra network bytes.
• Raster — a 72-bit integer (avg RGB + 3×2 greyscale) decoded to a tiny blurred SVG data-URI. No native dependency at render time.

Encoding uses sharp; decoding/rendering does not.

Install

npm i @alfred.westerveld/css-lqip
# sharp is an optional peer dependency, needed only for encoding:
npm i sharp

CLI

css-lqip compress photo.jpg            # prints css int, raster int, dominant hex
css-lqip compress photo.jpg --json
css-lqip decompress <raster-int> out.jpg --width 600 --height 400

Library

// Encoding (needs sharp)
import { encode } from '@alfred.westerveld/css-lqip';
const { css, raster, hex } = await encode('photo.jpg');

// Rendering (sharp-free — safe in browser/edge/SSR)
import { lqipCss, lqipStyle, rasterDataUri } from '@alfred.westerveld/css-lqip/decode';

// CSS-gradient placeholder: inject lqipCss() once, then per element:
//   <img loading="lazy" style={lqipStyle(css)} src="photo.jpg" />

// Raster placeholder:
const uri = rasterDataUri(raster); // data:image/svg+xml,...

Add the loaded class once the real image arrives to fade out the blur (lqipCss() ships the transition by default).

Exports

| Subpath | Needs sharp | Contents | | --- | --- | --- | | . | yes | encode, encodeCss, encodeRaster + everything from ./decode | | ./decode | no | lqipCss, lqipStyle, rasterDataUri, unpackCss, unpackRaster |

Credits

The 20-bit CSS-gradient format and its pure-CSS decoder are the work of Lean Rada — see CSS-only LQIP and the reference encoder. The decoder CSS in src/css.ts is used verbatim from that work; this package adds a sharp encoder, a 72-bit raster variant, a CLI, and an ESM library wrapper. All credit for the CSS-only LQIP technique goes to Lean Rada.