Visionary URL is a lightweight Typescript library for generating image URLs with built-in Blurhash placeholders.
Install visionary-url
via npm. Both ES modules and CommonJS modules are supported.
npm install --save visionary-url
import { generateVisionaryUrl } from 'visionary-url';
const url = generateVisionaryUrl({
blurhash: "LCDJYN9FxG_M_N%L%M%M4o~ptRIA", // blurhash string
blurhashX: 4, // blurhash x components
blurhashY: 4, // blurhash y components
bcc: "#baccae", // background color code
fileId: "image:101", // image ID or URL
sourceHeight: 1200, // image height
sourceWidth: 1600, // image width
});
A Visionary URL is formatted using 3 or 4 URL segments:
base path | visionary code | options (optional) | filename | ||||
---|---|---|---|---|---|---|---|
/ |
image |
/ |
<visionary code, base64url> |
/ |
<option tokens> |
/ |
image.jpg |
https://examplecdn.cloud/image/aW1hZ2U6MTAwMDEhODAwITYwMA/image.jpg
https://examplecdn.cloud/image/aW1hZ2U6MTAwMDEhODAwITYwMA/4k/image.jpg
The Visionary code is a base64url'd, exclamation-point separated list of image placeholder data, detailed as the following:
Attribute | Description |
---|---|
Image ID | Image URL or internal image ID (required) |
Image width | Used to compute aspect ratio of image placeholder (required) |
Image height | Used to compute aspect ratio of image placeholder (required) |
Background color code | Base layer background color code (e.g. #BACCAE ) |
Blurhash code | Blurhash string of the image |
Blurhash x components | Number of x components the blurhash code represents |
Blurhash y components | Number of y components the blurhash code represents |
Image options are optional and are provided as comma separated tokens.
One of the following tokens may be included in the options string to specify an image size: xs
, sm
, md
, lg
, xl
, xxl
, 4k
, 5k
token | description |
---|---|
download |
Indication for server to return content-disposition: attachment; in response headers |