Skip to main content

LQIPs (Low Quality Image Previews)

Low-quality image previews (LQIPs) provide a compact placeholder while a full image downloads. Konifer can generate two types:

  • BlurHash: Encodes a blurred color approximation as a short string
  • ThumbHash: Encodes color, aspect ratio, and optional transparency in a compact binary value

You can enable either format or both.

Note: Use a BlurHash or ThumbHash decoder in your application to render the placeholder. The projects linked above provide format details and implementation libraries.

Konifer creates LQIPs with eager and on-demand variants. It regenerates a preview only when a transformation changes the image data used by the preview. For example, a blur transformation reuses the existing LQIP.

Preview Example​

These previews decode the hashes Konifer returned for the same cow photo. Compare the broad areas of sky, trees, and grass with the finished image. A preview gives the page some of the image's color and structure while the image loads.

Cow in a mountain pasture with autumn trees and pale sky
Finished image · WebP · 480×360 pixels
Decoded BlurHash showing soft areas of pale sky, brown trees, and dark green grass
Decoded BlurHash
Decoded ThumbHash showing the cow scene as blurred areas of light and dark color
Decoded ThumbHash

All three occupy the same 4:3 display area. The previews above are saved PNG renderings of the returned hashes; your application would decode the hashes into placeholders, then replace them with the finished image.

The following request returns a link response containing the variant's attributes and LQIPs:

GET /assets/documentation/lqip/cow/-/link?format=webp&width=480

This excerpt contains the actual hashes used above:

{
"attributes": { "height": 360, "width": 480, "format": "webp" },
"lqip": {
"blurhash": "UnEyk|IUV@ni~qIUV@jF.8M|RQWB%gNIM|V[",
"thumbhash": "1ugVFYh1d4hfd4d6d5dniayTcOcJ"
}
}

Konifer returns BlurHash as a string and ThumbHash as Base64. Decode the ThumbHash string to bytes before passing it to a ThumbHash decoder. In this example, the BlurHash contains 36 characters and the ThumbHash contains 21 bytes before Base64 encoding. The sizes of the PNG illustrations do not represent the hash payload sizes.

Usage​

LQIPs are disabled by default. Enable both formats for a path with this configuration:

paths {
"/documentation/lqip/**" {
lqip = [
blurhash,
thumbhash
]
}
}

To reproduce the example, download the cow photo, save it as cow-original.jpg, and upload it after applying the configuration above:

curl --fail-with-body \
--request POST \
'http://localhost:8080/assets/documentation/lqip/cow' \
--form 'metadata={}' \
--form 'asset=@cow-original.jpg'

To disable inherited LQIPs for a child path, set lqip to an empty array:

paths {
"/**" {
lqip = [
blurhash,
thumbhash
]
}
"/users" {
lqip = []
}
}