Registry / web-framework / react-blurhash

react-blurhash

library0.3.0jsnpmunverified

react-blurhash provides React components for efficiently displaying Blurhash placeholders in web applications. Blurhash is a compact algorithm for representing a blurred version of an image, enabling a smooth user experience by showing a low-resolution placeholder while the full image loads. Currently at version 0.3.0, the package offers two core components: `<Blurhash />` for a higher-level, self-scaling implementation, and `<BlurhashCanvas />` for direct canvas rendering, offering granular control over the decoding and display process. The library ships with TypeScript types, enhancing developer experience and type safety. It's built upon the core `blurhash` algorithm and requires `react` (>=15) and `blurhash` (^2.0.3) as peer dependencies, which must be installed separately. The package is actively maintained, though its pre-1.0 version number suggests the API might evolve in future major releases.

web-framework serialization data

npm install react-blurhash

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-BLURHASH

react-blurhash

web-frameworkjavascriptv0.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Blurhash

✓ import { Blurhash } from 'react-blurhash';

✗ const { Blurhash } = require('react-blurhash');

This package is primarily designed for ES module environments. While CommonJS `require` might function through bundler transpilation, the idiomatic usage is ESM `import`. Ships with TypeScript types for direct use.

BlurhashCanvas

✓ import { BlurhashCanvas } from 'react-blurhash';

✗ const { BlurhashCanvas } = require('react-blurhash');

Use this component for direct canvas rendering when you need more control over scaling or if you're integrating into a custom image loading solution. Also includes TypeScript definitions.

BlurhashProps

✓ import type { BlurhashProps } from 'react-blurhash';

For TypeScript users, import prop types for explicit type checking and IDE auto-completion.

This quickstart demonstrates how to render a Blurhash placeholder using the `<Blurhash />` component. It illustrates basic usage with an example hash string and common props like width, height, and resolution. Remember to install `blurhash` and `react`.

import React from 'react'; import { Blurhash } from 'react-blurhash'; // Ensure you have installed peer dependencies: npm install blurhash react // This component displays a Blurhash placeholder. // In a real application, 'hash' would typically come from an image metadata API. function ImagePlaceholder() { const exampleHash = "LEHV6nWB2yk8pyo0adR*.7kCMdnj"; // Example Blurhash string return ( <div style={{ width: 400, height: 300, border: '1px solid #eee', overflow: 'hidden' }}> <h3>Blurhash Placeholder</h3> <Blurhash hash={exampleHash} width={400} height={300} resolutionX={32} resolutionY={32} punch={1} /> <p>Content will load over this placeholder...</p> </div> ); } export default ImagePlaceholder;

Debug

Known issues

breakingThe package is currently at version 0.3.0. As a pre-1.0 release, its API is not guaranteed to be stable and may introduce breaking changes in minor versions, though this is less common.

fix

Always check the release notes and changelog when upgrading, even for minor versions, and thoroughly test your application.

affects: <1.0.0

gotchaThe `blurhash` package is a required peer dependency and must be installed separately alongside `react-blurhash`. Forgetting to install it will lead to runtime errors.

fix

Ensure both `react-blurhash` and `blurhash` are installed: `npm install --save blurhash react-blurhash` or `yarn add blurhash react-blurhash`.

affects: >=0.1.0

gotchaUsing high values for `resolutionX` and `resolutionY` props (e.g., >128px) can significantly decrease rendering performance, especially when many Blurhash components are on the page.

fix

Optimize `resolutionX` and `resolutionY` to the lowest acceptable values (e.g., 32-64px) for your design to balance visual quality and performance. The default is 32.

affects: >=0.1.0

gotchaThe `width` and `height` props for `<Blurhash />` and `<BlurhashCanvas />` components must be numbers (integers or pixel values), not CSS string values like '100%'.

fix

If dynamic sizing is required, use React refs and the `ResizeObserver` API (or a library like `react-resize-detector`) to measure the parent container's dimensions and pass numerical `width` and `height` values to the Blurhash components.

affects: >=0.1.0

Errors

Common errors & fixes

Error: Cannot find module 'blurhash'

The core `blurhash` package, a required peer dependency, has not been installed.

fix

Install the `blurhash` package: `npm install blurhash` or `yarn add blurhash`.

ReferenceError: Uint8ClampedArray is not defined

The runtime environment (e.g., an older browser or a Node.js environment without a canvas polyfill for SSR) does not natively support `Uint8ClampedArray`, which the underlying `blurhash` library depends on.

fix

Ensure your target browser supports `Uint8ClampedArray` (most modern browsers do, >=IE11). For server-side rendering (SSR) in Node.js, you might need to use a canvas polyfill to provide this global object.

Warning: Failed prop type: Invalid prop `hash` of type `string` supplied to `Blurhash`, expected `string`.

The `hash` prop provided to the `Blurhash` or `BlurhashCanvas` component is either missing, empty, or malformed, leading to an invalid Blurhash string.

fix

Ensure the `hash` prop is a valid, non-empty Blurhash string. Validate the source of your Blurhash strings (e.g., from an API or encoding process).

Upgrade

Version history

0.3.0latest on npm

Audit

Dependencies

reactrequiredPeer dependency required for all React components.

blurhashrequiredCore Blurhash encoding/decoding logic; a peer dependency required by `react-blurhash`.

Agent activity

24 hits · last 30 days

node

Resources

githubhttps://github.com/woltapp/react-blurhash ↗

packagehttps://www.npmjs.com/package/react-blurhash ↗

homepagehttps://blurha.sh ↗