React Blurhash Component

Common errors

• Error: Cannot find module 'blurhash'

  cause 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

  cause 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`.

  cause 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).

Warnings

• breaking The 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.
• gotcha The `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`.
• gotcha Using 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.
• gotcha The `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.

Install

• npm install react-blurhash npm
• yarn add react-blurhash yarn
• pnpm add react-blurhash pnpm

Imports

• Blurhash
  wrong:

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

  correct:

  import { Blurhash } from '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
  wrong:

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

  correct:

  import { BlurhashCanvas } from '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.

Quickstart

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;