Visionary Image

SSR-ready Blurhash placeholders for React and Web Components that speed up pageload and improve Core Web Vitals.

Features

• Easy Blurhash: Get started with Blurhash in 60 seconds.
• Layout stability: Eliminates Cumulative Layout Shift (CLS) with true-to-size, responsive placeholders.
• Automatic lazy loading: Off-screen images are deferred, reducing initial pageload size and optimizing Interaction to Next Paint (INP).
• Lightning-fast previews: Paints placeholders in the browser's Critical Rendering Path (at First Contentful Paint, before DOMContentLoaded) using URL-embedded Blurhash data, powered by blurhash-url.
• Framework-ready: Works with Next.js, Remix, and Vite and supports both client and server-side rendering (SSR, SSG).
• Additional features: Prevent image dragging; prevent user selecting image
• Developer friendly: Written in TypeScript and unit tested.
  • Check out the interactive Storybook sandbox
• Search performance: Enhance search ranking potential by improving Core Web Vitals scores.

  "We highly recommend site owners achieve good Core Web Vitals for success with Search" — Google Search Central

Lighthouse Performance

See our PageSpeed Insights Report →

Lighthouse filmstrip showing the three-layer load: background color → Blurhash → full image

Installation

Install via npm, yarn, or pnpm.

pnpm add visionary-image

Usage

Begin by creating a Blurhash URL. This is then passed to the src prop of the Image component.

Creating a Blurhash URL

There are several ways to create a Blurhash URL.

1. Use the Blurhash URL Maker for public image URLs
2. Use the Drag & Drop Blurhash Generator for local image files
3. Use blurhash-url to programmatically generate a URL

Render Image

import { Image } from "visionary-image";

const ImageDetails = () => <Image alt="..." src="<Blurhash URL>" />;

Component Props

| Name | Description | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | alt string | Image alt tag. Adding alt text to images is highly recommended to accommodate accessible devices and improve discoverability. | | bgColorAlpha number | Base layer (background color) alpha channel. Default: 0.7 | | className string | Classname applied to the container div or the fallback img element. | | debug boolean | Prints handy debug info to the console (Blurhash URL data, render times). | | disableBlurLayer boolean | Disables rendering of the blur (canvas) layer. | | disableImageLayer boolean | Disables rendering of the image layer. | | height number, string | If set, will override internally computed image height. By default, Visionary renders optimally sized images, using the aspect-ratio and max-width placeholder data. | | hideImageLayer boolean | Hides the image layer, revealing the blur layer underneath. | | lazy boolean | Should image load lazily. Default: true | | onClick function | Callback function to invoke when the image is clicked. function. | | onError function | Error callback function. | | onLoad function | Image loaded callback function. | | preventDrag boolean | Prevents user from dragging the image element. | | preventSelection boolean | Prevents user from highlighting the image element. | | priority boolean | Mark as priority image (above-the-fold). Sets fetchpriority="high" and loading="eager". Use for LCP images. Default: false | | punch number | Blurhash punch parameter. Default: 1 | | src string | Blurhash URL, Visionary Code, or ordinary image URL. If src contains Blurhash URL data, placeholders will be rendered, otherwise falls back to an img element. required | | width number, string | If set, will override internally computed image width. By default, Visionary renders optimally sized images, using the aspect-ratio and max-width placeholder data. |

Relevant Questions

Do image placeholders render server-side?

Yes. With server-side rendering (SSR) or static site generation (SSG), the placeholder's first layer (the solid background) renders in the initial HTML. This reserves the image's layout space and is painted on the Critical Rendering Path, early enough to affect First Contentful Paint (FCP), before DOMContentLoaded. The Blurhash and image layers then render client-side.

How long does the Blurhash canvas take to load?

Canvas operations are highly efficient in modern browsers. Rendering the 24x24 pixel Blurhash placeholder typically takes less than 1ms.

What is Blurhash and where can I learn more?

Blurhash uses Discrete Cosine Transforms to represent a color-accurate image placeholder as a compact string (in 20-30 characters). Check out the official Blurhash docs for more info.

Related packages

| Package | Use for | | -------------------------------------------------------------------------- | ------------------------------------------------------------------ | | visionary-image (this package) | React apps (<Image />), or the <visionary-image> web component | | visionary-image-js | Zero-config <script> / CDN, or framework-agnostic SSR HTML |