BlurHash generator and decoder

A BlurHash generator stores a suggestion, not a miniature original

BlurHash describes broad color and shape with a short base83 string. A decoder can paint that suggestion before the real image arrives, but it cannot restore edges, text or the source pixels. That is why the preview here is deliberately soft and why its checksum verifies the decoded pixels rather than claiming similarity to the original.

The first character stores the component grid. More components can retain more directional variation, but they also lengthen the string and make noise easier to preserve. Four horizontal by three vertical components is a practical starting point for landscape photographs. Logos, flat graphics and extreme aspect ratios deserve a deliberate comparison rather than a universally larger number.

Dimensions and aspect ratio live beside the hash

A BlurHash string does not contain the original width, height or intended aspect ratio. The same hash can be decoded to 32×18, 320×180 or a square. Those outputs contain the same coefficients stretched over different canvases. Store source dimensions or an aspect ratio in your own record and size the placeholder container before the full image loads.

The JSON example therefore carries three separate values: hash, width and height. The dimensions are metadata, not a reverse-engineered property of the string. If you need the original image itself in a textual wrapper, image to Base64 preserves the file bytes instead; it produces a much larger result and solves a different job.

Transparent images need an explicit background

The algorithm operates on red, green and blue. There is no alpha coefficient. This page composites transparent pixels onto the color shown in the control before the 64-pixel sample is encoded. Pick the same surface the eventual image will sit on, especially for antialiased logos whose edge pixels are only partly opaque.

If the source needs its background removed first, the transparent background maker produces an editable alpha mask. Return here afterward and choose the destination surface explicitly. For byte or dimension reduction of the final full image, use compress image; BlurHash does not compress the source asset and should not replace it.

The local receipt is intentionally narrow

The source is decoded by the browser, reduced to at most 64 pixels on its longest side, composited and passed to the official TypeScript implementation. The returned hash is decoded again into the visible canvas. Its component grid, string length and a checksum of the rendered RGBA buffer are shown together so a changed hash or dimension cannot masquerade as the same preview.

This verifies local mechanics, not visual quality on every photograph and not a framework integration. Browsers and native apps still need a compatible decoder, and the CSS platform has no built-in BlurHash function. The bulk image resizer remains the right route when the deliverable is a set of real raster files at exact dimensions.

BlurHash and ordinary LQIP are related but not interchangeable

A conventional LQIP is a deliberately tiny JPEG, PNG or WebP that the browser already knows how to draw. It can be embedded as a data URI, blurred with CSS and replaced later. BlurHash spends fewer textual characters on a coefficient model, but requires decoding code before it becomes pixels. Choose based on the delivery system you control, not on the word “placeholder” alone.