candlefinance/faster-image

Fast image loading for React Native backed by performant native libraries.

image-demo.mp4

A performant way to render images in React Native with a focus on speed and memory usage. Powered by Nuke, the smallest and most performant image loading library for iOS and macOS and Coil on Android.

The framework is lean and compiles in under 2 seconds¹. Nuke has an automated test suite 2x the size of the codebase itself, ensuring excellent reliability. Every feature is carefully designed and optimized for performance.

Coil performs a number of optimizations including memory and disk caching, downsampling the image in memory, automatically pausing/cancelling requests, and more.

Features

• Supports visionOS
• Fast image loading
• Memory and disk caching
• Placeholder support:
  • blurhash (iOS only)
  • thumbhash (iOS only)
  • Base64 encoded image
• Animated transition
• Failure image
• Typescript support
• Written in Swift/Kotlin

Installation

yarn add @candlefinance/faster-image

Usage

import { FasterImageView, clearCache } from '@candlefinance/faster-image';

<FasterImageView
  style={styles.image}
  onSuccess={(event) => {
    console.log(event.nativeEvent);
  }}
  onError={(event) => console.warn(event.nativeEvent.error)}
  source={{
    transitionDuration: 0.3,
    borderRadius: 50,
    cachePolicy: 'discWithCacheControl',
    showActivityIndicator: true,
    url: 'https://picsum.photos/200/200?random=1',
  }}
/>;

// Clear memory and disk cache
await clearCache();

Props

Prop	Type	Default	Description
url	string		The URL of the image
style	object		The style of the image
resizeMode	string	contain	The resize mode of the image
thumbhash	string		The thumbhash of the image as a base64 encoded string to show while loading (Android not tested)
blurhash	string		The blurhash of the image to show while loading (iOS only)
showActivityIndicator	boolean	false (iOS only)	Whether to show the UIActivityIndicatorView indicator when the image is loading
base64Placeholder	string		The base64 encoded placeholder image to show while the image is loading
cachePolicy	string	memory	The cache policy of the image
transitionDuration	number	0.75 (iOS) Android (100)	The transition duration of the image
borderRadius	number	0	border radius of image
failureImage	string		If the image fails to download this will be set (blurhash, thumbhash, base64)
progressiveLoadingEnabled	boolean	false	Progressively load images (iOS only)
onError	function		The function to call when an error occurs. The error is passed as the first argument of the function
onSuccess	function		The function to call when the image is successfully loaded
grayscale	number	0	Filter or transformation that converts the image into shades of gray (0-1).
allowHardware	boolean	true	Allow hardware rendering (Android only)
headers	Record<string, string>	undefined	Pass in headers
accessibilityLabel	string	undefined	accessibility label
accessible	boolean	undefined	is accessible

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

faster-image's Issues

android: Error while updating property 'source' of a view manage by: FasterImageView null null

After upgrading from 1.3.4 to 1.4.1, I consistently get this redbox error:

I made sure to gradlew clean and then tried to narrow down all of the source references by hardcoding to a well known public url and removing styling, but no luck.

v1.3.4 was working well, just needed your fix for borderRadius 👍

Thanks for providing an alternative to the dead react-native-fast-image!

❯ npx react-native info
info Fetching system and libraries information...
System:
  OS: macOS 13.6.4
  CPU: (10) arm64 Apple M1 Max
  Memory: 100.41 MB / 32.00 GB
  Shell:
    version: "5.9"
    path: /bin/zsh
Binaries:
  Node:
    version: 20.12.0
    path: ~/.nvm/versions/node/v20.12.0/bin/node
  Yarn:
    version: 1.22.19
    path: ~/.nvm/versions/node/v20.12.0/bin/yarn
  npm:
    version: 10.5.0
    path: ~/.nvm/versions/node/v20.12.0/bin/npm
  Watchman:
    version: 2024.01.22.00
    path: /opt/homebrew/bin/watchman
Managers:
  CocoaPods:
    version: 1.15.2
    path: /opt/homebrew/bin/pod
SDKs:
  iOS SDK:
    Platforms:
      - DriverKit 23.2
      - iOS 17.2
      - macOS 14.2
      - tvOS 17.2
      - watchOS 10.2
  Android SDK: Not Found
IDEs:
  Android Studio: 2022.3 AI-223.8836.35.2231.10811636
  Xcode:
    version: 15.1/15C65
    path: /usr/bin/xcodebuild
Languages:
  Java:
    version: 11.0.22
    path: /usr/bin/javac
  Ruby:
    version: 2.7.7
    path: /Users/jamesholcomb/.rbenv/shims/ruby
npmPackages:
  "@react-native-community/cli": Not Found
  react:
    installed: 18.2.0
    wanted: 18.2.0
  react-native:
    installed: 0.72.7
    wanted: 0.72.7
  react-native-macos: Not Found
npmGlobalPackages:
  "*react-native*": Not Found
Android:
  hermesEnabled: true
  newArchEnabled: false
iOS:
  hermesEnabled: true
  newArchEnabled: false

resizemode and borderRadius not working

I switch from expo-image to this component. Performance is good, but I cannot change the resizeMode of my image. I stuck at "strech" mode event I change to "contain".

And borderRadius in style is not working, too.

Please help. Thanks!

GIF support

Hey! Thanks for this great library - am I correct in saying that the library currently doesn't load GIFs? For me, none of the GIFs are playing.

Would be great to know if this is a bug or just not supported yet. thank you

Does it support for react native web?

`resizeMode` is having no effect (iOS) and image is stretched by default.

<FasterImageView source={{ resizeMode: 'cover', url: entry?.image, transitionDuration: 0.2, }} style={{ width: Dimensions.get('window').width, height: 300, }} />

version -> "@candlefinance/faster-image": "^1.3.3"

hello. loving this library and considering adding this to our project but it appears as though the resizeMode prop is having no effect. we want to set it to "cover" but nothing is happening. screenshot is from an iOS simulator running on debug mode

Clear cache

Is there a way to clear cache, or plans to implement this feature? This would be useful for testing/debug.

I think in Nuke for iOS it'll look something like this

Nuke.Cache.shared.removeAll()
Nuke.DataLoader.sharedUrlCache.removeAllCachedResponses()

and Coil for Android looking like this

fun clearCache(context: Context, memory: Boolean = true, file: Boolean= true) {
    // 1) clear memory cache
    if (memory) {
        val imageLoader = context.imageLoader
        imageLoader.memoryCache.clear()
    }
    // 2) clear file cache
    if (file) {
        val cache = CoilUtils.createDefaultCache(context)
        cache.directory().deleteRecursively()
    }
}

I can maybe take a look and open a PR sometime this week, unless someone beats me to it 😁

No access to readme video

Hey,

Thought I would let you know I can't seem to load the readme video.

Question/border radius: what is more recommended – use style or source?

What is more recommended when applying border radius – to apply it via the style or via the source?
Same question regarding the resizeMode

Thank you for this great library!

Add headers to image request

I have a use case where I'm using authorization headers, and the React Native Image component allows me to pass those directly into the source of an Image. It would be great if the same thing would work with this library!

Theoretical example:

<FasterImageView source={{
  uri: src,
  headers: {
    Authorization: `Bearer ${token}`,
  },
 }} />

feature request: tint

Both FastImage and Expo Image supports "tint", i.e. changing the color tint of an image. Any plans to support that?

How to load local images?

Hello, when i try to load url images it works without any issues, but i'm still trying to figure how to load local images (.png), is it supported?

Thank you.

Memory spike with 100+ huge images.

I made a reproducer here, just by increasing the image sizes.
https://github.com/bglgwyng/faster-image/tree/reproduce-memory-spike

I considered this library an alternative expo-image as it also has the memory spike problem. See expo/expo#26781.

I tried both expo-image and faster-image in a gallery view that renders 100+ images with a size of 1920x1080, 1MB each.
I don't consider it a too pathological case as many gallery-like views would do the same, but both libraries crashed the app with a memory spike.

I wonder why the memory spike is so high. It reaches 2GB for 100 images, which is 20MB per image.
I understand the image is decompressed and stored in memory, but 20MB for a 1MB image seems too much.
Image in react-native loads images slower, but it uses much less memory and works fine with 100+ images. How is it possible? Which difference in the implementation causes this?

Also, I have a question if just throttling the image loading helps in this case.
Throttling the image loading seems trivial, so I suspect that it can affect the user experience as it slows down the image loading, and that's the reason why expo-image and faster-image don't do it.

In my case which renders 100+ images but in a smaller size as thumbnails, so caching the resized images would be helpful.
It doesn't seem that expo-image and faster-image do so.

[FEATURE] support for react-native-windows and react-native-macos

support for react-native-windows and react-native-macos should be available as react native is ready to cover all 4 platforms and we need these things in our apps

Local png file?

How do we deliver local images using this? We want to deprecate but cannot find a way to pass a require('localfile.png') to it.

Can not run pod-install

I would like to try this library to increase our application

I followed the document just run: yarn add @candlefinance/faster-image but then when I ran our app, I got the error:
"requireNativeComponent: "FasterImageView" was not found in the UIManager."
So, I tried to run npx pod-install, and also pod install but I got another error:
"cocoaPods could not find compatible versions for pod "FasterImage":
In Podfile:
FasterImage (from ../node_modules/@candlefinance/faster-image)

Specs satisfying the FasterImage (from ../node_modules/@candlefinance/faster-image) dependency were found, but they required a higher minimum deployment target."

Then, I edited our Podfile with the current minimum_targer from "12.4" to "13.0" (follow platforms in your library podspec) but the error still stays.

Please help me in this situation. I want to try your library to increase our application performance. Thanks

[Question] FlashList recycling support?

Hi!
Damn,, this was a good lib fr.
But I want to know, does this lib support recycling with FlashList just like Expo Image did?

Thanks for this very nice libs, Gary!

Cache not used on Android

On version 1.5.0, the cache is used on IOS but on the same app on Android it does not work.
I was surprised to see that with the basic RN Image component the cache seems to work on Android but not on IOS.
I tried with differents cache policies with same results.

accessibility support

Thank you for this lib, are there any plans to add accessibility support?

Aspect Ratio

Is it possible to set the aspect ratio for an image?

Android support

Implement the Android side of loading an image async.

• https://github.com/coil-kt/coil
• https://github.com/bumptech/glide
• https://github.com/facebook/fresco

resizeMode and borderRadius inconsistencies on Android

Hey. Thanks for promptly responding to the previous report. Found a couple more issues on android.

1. resizeMode not reflected and defaults to "contain"

2. borderRadius value doesn't match the React Native values (this is only on android as well). I have added a border radius of 10 on both the image an the view wrapping it. Added a border line in red to emphasise.

Image not loading on android (only production vesrion)

I have a specific issue. When I submit my app to google play store and internally test it, In a specific screen, my images are not loading. This screen is the first screen in my app. The images load perfectly on each other screen, and on that screen on ios and on the debug build on android. Worth noting I am working within the expo workflow but with a prebuild.

Not sure how this would be reproducible but I would love help debugging this so I don't have to use a different package.

Comparison with Expo Image and FastImage?

The package looks great! Nice to see someone picking up the void from the unmaintained FastImage!

However - One thing I'm missing in the docs is a comparison between FastImage (since it has a lot of users), and the more recent Expo Image. It would make it easier to understand why/when to pick one over the other.

Setting border radius just on top corners

I am trying to set border radius on top but it's not working

`
<FasterImageView
source={{
url: meme.image,
resizeMode: 'contain',
}}
style={{
...styles.image,
borderTopLeftRadius: 10 ,
borderTopRightRadius: 10,
}}
/>

`

is it possible to add borderRadius just on top or just bottom?