Blurhash URL

Anatomy of a Blurhash URL

  decodedBlurhash
  {
    backgroundColor: "#f88a7b",
    blurhash: "KeQ=~sxG^6vCf7R+}sjt9]",
    blurhashX: 3,
    blurhashY: 3,
  }
                

A Blurhash URL consists of 3 or 4 path segments:

Example Blurhash URL

The bold section is the encoded Blurhash Code containing the placeholder data.

Blurhash Code

The Blurhash Code is a base64url-encoded string containing the following fields (in order):

The first three fields (image ID, width, and height) are required to render a properly sized placeholder. If the other fields are omitted, a placeholder with a semi-transparent black background (rgba(0, 0, 0, 0.7)) will be rendered.

Fields are separated by an exclamation mark (!) before being base64url-encoded. This separator was chosen to avoid conflicts with characters used by Blurhash’s base83 encoding.

Image Options

Image options control how the image is served. To add them, include comma-separated tokens in the URL segment between the Blurhash Code and the filename.

Options should be sorted alphabetically (e.g., download,jpeg not jpeg,download) to ensure consistent URLs for the same set of options. This maximizes cache hit rates across browsers and CDNs. When you generate URLs with blurhash-url, options are automatically sorted.

Example: Options tokens instructing the server to return an xl sized image as a downloadable file:

Format Tokens

Specify the image format using one of the following tokens:

Control Tokens

Image Resolutions

Specify the image resolution using a size token in the options segment. The size token constrains the image’s longest edge (width or height) to the specified pixel value, preserving the original aspect ratio.

For example, a 4k token applied to a 6000×4000 landscape image produces a 3840×2560 output. The same token applied to a 4000×6000 portrait image produces a 2560×3840 output.

Size Token Reference

Resolution Details

xs — 160px (Tiny)

Best for micro-thumbnails where image detail is not important. At 160px on the long edge, these are ideal for small avatar images, icon-sized previews, or image list indicators. Produces the smallest file sizes for maximum performance.

sm — 320px (Small)

Suitable for thumbnail grids and small card images. At 320px, this covers typical thumbnail sizes used in galleries, search results, and small mobile layouts. Roughly equivalent to an older smartphone screen width.

md — 640px (Medium)

A versatile mid-range size. At 640px, images look sharp on mobile devices at full viewport width and work well for email content, social sharing previews, and embedded media in articles. Close to classic VGA resolution (640×480).

lg — 1280px (Large) — Default

The default size token. At 1280px, images are sharp on standard desktop monitors and laptops. This corresponds to HD-class resolution (1280×720 / 720p) and covers the majority of standard web use cases: blog posts, product pages, and content images. A good balance between quality and file size.

xl — 1920px (X-Large)

Matches Full HD resolution (1920×1080 / 1080p), the most common desktop display resolution worldwide. Ideal for full-width hero banners, landing page backgrounds, and full-viewport desktop images. Sometimes referred to as “2K” in consumer contexts, though true DCI 2K is 2048×1080.

xxl — 2560px (XX-Large)

Covers QHD (Quad HD) resolution, also known as 1440p or WQHD (2560×1440). Common on high-end desktop monitors, gaming displays, and 13–14“ Retina laptop screens where the OS renders at an effective 1280px at 2× density. Also covers 2K in the professional cinema sense (2560×1440).

4k — 3840px

4K UHD (Ultra High Definition), the resolution of modern 4K TVs and monitors (3840×2160). Also covers the true DCI 4K cinema standard (4096×2160) when images are wide enough. Use this for large-format displays, digital signage, or when serving images on high-density screens at large viewport sizes.

5k — 5120px

5K resolution (5120×2880), found on displays like the Apple Studio Display and iMac Retina. This resolution enables pixel-perfect rendering at an effective 2560px at 2× Retina density. Use for ultra-high-resolution use cases where maximum detail is required.

full — Source Resolution

Serves the image at its original uploaded resolution with no downscaling. Use when you need the exact source quality — for example, for download links, print preparation, or when users need access to the highest-resolution version available.

Filename

The last path segment is the filename. Defaults to image.jpg.

Use descriptive filenames (e.g. tokyo-shibuya-crossing-neon-rainy.jpg) to improve image discoverability in search engines.

The filename can also be modified to force a cache refresh. If an outdated image is still being served due to caching, append a version number or date (e.g. starship-stacked-v2.jpg or starship-stacked-20250609.jpg) to ensure the latest version is loaded.

Using Your Own Domain

To configure your domain to serve Blurhash URLs, simply set up two routes in your server:

app.get("/image/:blurhashCode/:filename", handler);
app.get("/image/:blurhashCode/:options/:filename", handler);

The handler extracts the Blurhash placeholder data from the URL and serves the corresponding image:

import { parseVisionaryString } from "blurhash-url";

export const handler = (request: Request) => {
  const data = parseVisionaryString(request.url);
  const imageUrl = data.fields.url;

  // Load, serve, or redirect your image as needed
};