BlurHash generation for images.
BlurHash is a compact representation of a placeholder for an image. A 20–30 character ASCII string encodes a low-fidelity blurred version of the image that can be rendered on the client before the real image loads, without any additional HTTP round-trips.
Comparison with Tiny JPEG Placeholders
PhxMediaLibrary already generates tiny JPEG placeholders (≈ 500–2 KB). BlurHash strings are typically 20–40 bytes and are stored directly in the database field, making them easier to embed in JSON APIs and server-rendered HTML without base64 overhead.
Requirements
Blurhash generation requires the :image library (libvips wrapper). The
feature is silently disabled when the library is not available.
Configuration
config :phx_media_library,
responsive_images: [
enabled: true,
blurhash: true # opt-in
]Usage
When enabled, a blurhash string is automatically generated for every image
upload and stored in media.responsive_images["blurhash"].
Render it in a template with the <PhxMediaLibrary.Components.blurhash>
component, which decodes the hash client-side via a colocated JS hook and
paints it onto a <canvas> element.
<PhxMediaLibrary.Components.blurhash media={@media} class="w-full rounded-lg" />You can also call the generator directly:
{:ok, hash} = PhxMediaLibrary.Blurhash.generate("/path/to/image.jpg")
#=> {:ok, "LKO2?V%2Tw=w]~RBVZRi};RPxuwH"}Component X/Y Components
The number of DCT components controls the detail vs. string-length trade-off. The default is 4×3 (12 components, ~28 chars). You can adjust per-call:
{:ok, hash} = PhxMediaLibrary.Blurhash.generate(path, components_x: 5, components_y: 4)Values above 8×8 are uncommon; the official recommendation is 4×3 or 3×4.
Summary
Functions
Returns true when the :image library is available and blurhash
generation is possible.
Generate a BlurHash string from an image file path or an in-memory
%Vix.Vips.Image{}.
Functions
@spec available?() :: boolean()
Returns true when the :image library is available and blurhash
generation is possible.
Generate a BlurHash string from an image file path or an in-memory
%Vix.Vips.Image{}.
The image is automatically resized to a small working size (64 px wide) before the DCT components are computed, so performance is consistent regardless of the input resolution.
Arguments
source— file path (String.t()) or an already-opened%Vix.Vips.Image{}struct.opts— keyword options.
Options
:components_x— number of DCT components in the horizontal direction (1–9, default:4).:components_y— number of DCT components in the vertical direction (1–9, default:3).
Return value
{:ok, hash_string} on success, or {:error, reason} on failure.
Examples
iex> PhxMediaLibrary.Blurhash.generate("priv/static/uploads/photo.jpg")
{:ok, "LKO2?V%2Tw=w]~RBVZRi};RPxuwH"}
iex> PhxMediaLibrary.Blurhash.generate("photo.jpg", components_x: 5, components_y: 4)
{:ok, "..."}