visionary-image v1.0.4
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-imageUsage
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.