visionary-image

Visionary Image

React image component with built-in Blurhash placeholders for better UX and 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).
• Lighning-fast previews: Renders placeholders early (by initial DOM layout) using URL-embedded Blurhash data, powered by visionary-url.
• Framework tested: Compatible with Remix, Next.js, 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

Lighthouse report filmstrip showing three-layer image loading process

Installation

Install via npm, yarn, or pnpm.

npm install --save visionary-image

Usage

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

Creating a Visionary Image URL

There are several ways to create a Visionary URL.

• Use the Visionary URL Maker for public image URLs
• Use the Drag & Drop Blurhash Generator for local image files
• Use visionary-url to programmatically generate a URL

Render Image

import { Image } from "visionary-image";

const ImageDetails = () => <Image alt="..." src="<Visionary 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 (Visionary 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.
punch number	Blurhash punch parameter. Default: 1
src string	Visionary URL, Visionary Code, or ordinary image URL. If src contains Visionary 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, Visionary Image supports server-side rendering (SSR) and static site generation (SSG), as well as client-side rendering. In server-rendered scenarios, the first layer (background color) renders immediately, followed by the Blurhash and image layers once the page loads in the client's browser.

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 around 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.