Miss any of our Open RFC calls?Watch the recordings here! »

react-native-blurhash

1.0.27 • Public • Published

Blurhash

🖼️ Give your users the loading experience they want.

Install via npm:

npm i react-native-blurhash
cd ios; pod install; cd ..

Buy Me a Coffee at ko-fi.com

npm npm GitHub stars GitHub followers

BlurHash is a compact representation of a placeholder for an image. Instead of displaying boring grey little boxes while your image loads, show a blurred preview until the full image has been loaded.

The algorithm was created by woltapp/blurhash, which also includes an algorithm explanation.

Turn grey image boxes into colorful blurred images

Example Workflow

    In order to use the Blurhash component, you have to already have a Blurhash string. See the blurha.sh page to create example strings.

    This is how I use it in my project:

  1. A user uploads images from the react native app to firebase
  2. In firebase, I have a storage trigger function that generates a blurhash string from the uploaded image using the encoder from the C implementation. (You can also use the integrated encoder to encode an Image straight out of your React Native App!)
  3. After I generated the blurhash string, I set this as a property on my post document in Firestore
  4. Now everytime a user loads a feed of posts from my Firestore database, I show a <Blurhash> component (with the post's .blurhash property) over my <Image> component, and fade it out once the <Image> component's onLoadEnd function has been called.

Usage

The <Blurhash> component has the following properties:

Name Type Explanation Required Default Value
blurhash string The blurhash string to use. Example: LGFFaXYk^6#M@-5c,1J5@[or[Q6. undefined
decodeWidth number The width (resolution) to decode to. Higher values decrease performance, use 16 for large lists, otherwise you can increase it to 32.
See: performance
32
decodeHeight number The height (resolution) to decode to. Higher values decrease performance, use 16 for large lists, otherwise you can increase it to 32.
See: performance
32
decodePunch number Adjusts the contrast of the output image. Tweak it if you want a different look for your placeholders. 1.0
decodeAsync boolean Asynchronously decode the Blurhash on a background Thread instead of the UI-Thread.
See: Asynchronous Decoding
false
resizeMode 'cover' | 'contain' | 'stretch' | 'center' Sets the resize mode of the image. (no, 'repeat' is not supported.)
See: Image::resizeMode
'cover'
onLoadStart () => void A callback to call when the Blurhash started to decode the given blurhash string. undefined
onLoadEnd () => void A callback to call when the Blurhash successfully decoded the given blurhash string and rendered the image to the <Blurhash> view. undefined
onLoadError (message?: string) => void A callback to call when the Blurhash failed to load. Use the message parameter to get the error message. undefined
All View props ViewProps All properties from the React Native View. Use style.width and style.height for display-sizes. Also, style.borderRadius is natively supported on iOS. {}

Example Usage:

import { Blurhash } from 'react-native-blurhash';
 
export default function App() {
  return (
    <Blurhash
      blurhash="LGFFaXYk^6#M@-5c,1J5@[or[Q6."
      style={{flex: 1}}
    />
  );
}

See the example App for a full code example.

iOS Screenshot Android Screenshot
iOS Demo Screenshot Android Demo Screenshot

Average Color

If your app is really colorful you might want to match some containers' colors to the content's context. To achieve this, use the getAverageColor function to get an RGB value which represents the average color of the given Blurhash:

const averageColor = Blurhash.getAverageColor('LGFFaXYk^6#M@-5c,1J5@[or[Q6.')

Encoding

This library also includes a native Image encoder, so you can encode Images to blurhashes straight out of your React Native App!

const blurhash = await Blurhash.encode('https://blurha.sh/assets/images/img2.jpg', 4, 3)

Because encoding an Image is a pretty heavy task, this function is non-blocking and runs on a separate background Thread.

Performance

The performance of the decoders is really fast, which means you should be able to use them in collections quite easily. By increasing the decodeWidth and decodeHeight props, the time to decode also increases. I'd recommend values of 16 for large lists, and 32 otherwise. Play around with the values but keep in mind that you probably won't see a difference when increasing it to anything above 32.

Asynchronous Decoding

Use decodeAsync={true} to decode the Blurhash on a separate background Thread instead of the main UI-Thread. This is useful when you are experiencing stutters because of the Blurhash's decoder - e.g.: in large Lists.

Threads are re-used (iOS: DispatchQueue, Android: kotlinx Coroutines).

Caching

Image

Previously rendered Blurhashes will get cached, so they don't re-decode on every state change, as long as the blurhash, decodeWidth, decodeHeight and decodePunch properties stay the same.

Cosine Operations

Cosine operations get cached in memory to avoid expensive re-calculation (~24.576 cos(...) calls per 32x32 blurhash). Since this can affect memory usage, you can manually clear the cosine array cache by calling:

Blurhash.clearCosineCache()

Resources

Buy Me a Coffee at ko-fi.com

Install

npm i react-native-blurhash

DownloadsWeekly Downloads

730

Version

1.0.27

License

MIT

Unpacked Size

94.8 kB

Total Files

35

Last publish

Collaborators

  • avatar