🖼️ A library to show colorful blurry placeholders while your content loads.
MIT License
🖼️ Give your users the loading experience they want.
Install via npm:
npm i react-native-blurhash
npx pod-install
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.
This is how I use it in my project:
The <Blurhash>
component has the following properties:
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.
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.')
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.
If you need to validate a blurhash string, you can use isValidBlurhash
.
const result = Blurhash.isValidBlurhash('LGFFaXYk^6#M@-5c,1J5@[or[Q6.')
if (result.isValid) {
console.log(`Blurhash is valid!`)
} else {
console.log(`Blurhash is invalid! ${result.reason}`)
}
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
.
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).
A <Blurhash>
component caches the rendered Blurhash (Image) as long as the blurhash
, decodeWidth
, decodeHeight
and decodePunch
properties stay the same. Because unmounting the <Blurhash>
component clears the cache, re-mounting it will cause it to decode again.
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()
Note: At the moment, cosine operations are only cached on Android. Calling
clearCosineCache()
is a no-op on other platforms.