React Native Image Cache on File System with Progressive Loading with Dynamic Links (Amazons S3 and etc.)
Fork of:
Inspired by:
- wcandillon/react-native-expo-image-cache (William Candillon)
- WrathChaos/react-native-progressive-fast-image (FreakyCoder)
Features
A fork of @georstat/react-native-image-cache with a usage of a link without params as a caching key! Could be useful for caching images from Amazon S3 and similar sources.
- Cache remote images in file system with progressive loading
- Uses
react-native-file-access
for file system access - Written in
Typescript
- Uses
react-native-reanimated
for animations
Caution:
react-native-reanimated
version 2.x.x then use version 1.x.x of this module
If you're not using @georstat/react-native-image-gallery
If you're looking for an image library with thumbnails visitPreview
iOS:
Android:
example)
Custom Loading Image Component: (seeInstallation
yarn:
yarn add @georstat/react-native-image-cache
npm:
npm i @georstat/react-native-image-cache
link native packages:
cd ios
pod install
**note!
For react native >= 0.65 use react-native-file-access
>= 2.0.0
Usage
App.tsx
or index.js
(Required):
Put this Global config on your app entry eg. import { CacheManager } from '@georstat/react-native-image-cache';
import { Dirs } from 'react-native-file-access';
CacheManager.config = {
baseDir: `${Dirs.CacheDir}/images_cache/`,
blurRadius: 15,
cacheLimit: 0,
sourceAnimationDuration: 1000,
thumbnailAnimationDuration: 1000,
};
cacheLimit
config: (auto pruning of cached files)
If cacheLimit
is set to 0
(default value) then the cache will never be auto pruned. This setting accepts a number of Bytes eg. 1024 * 1024 * 256
(~256MB) and requires react-native-file-access
>= 2.4.0, if you're using < 2.4.0 then leave the default value 0
(disabled).
Cache pruning flow:
- Get all files from
baseDir
. - Sort them by
lastModified
, oldest first. - Get total size in Bytes by using
reduce
array method. - Check total size from step 3 and subtract
cacheLimit
value. - Run a while loop and keep deleting files so long as the current cache size (step 4) is larger than the size required to trigger cache pruning (
cacheLimit
value). - All steps above will run only if the image is not already cached, it runs after downloading a new image into the cache.
Pruning has been benchmarked on iOS simulator with a 5.7MB image and ~5.000 copies of it on cache without any issues. Please note that the pruning speed/performance might differ among devices. Use cacheLimit
wisely and do not set a big value.
If you want to run your own tests on simulator then the cached images are stored in this location on a Mac:
/Users/<your_name>/Library/Developer/CoreSimulator/Devices/<simulator_device_id>/ data/Containers/Data/Application/<application_id>/Library/Caches/images_cache
,
just copy and paste multiple images in there, there's no need to download them via the app.
react-native-file-access docs)
Directory constants, choose wisely: (Dirs.CacheDir
-
Dirs.DatabaseDir
(Android only) Dirs.DocumentDir
-
Dirs.LibraryDir
(iOS only) Dirs.MainBundleDir
-
Dirs.SDCardDir
(Android only)- Prefer
FileSystem.cpExternal()
when possible.
- Prefer
Component:
import { CachedImage } from '@georstat/react-native-image-cache';
<CachedImage
source="https://via.placeholder.com/3500x3500"
style={{ height: 350, width: 150 }}
thumbnailSource="https://via.placeholder.com/350x150"
/>;
Prefetch Image(s) and store them in cache:
Accepts 2 parameters:
Parameter | Type | Description |
---|---|---|
image |
Array or String |
(Required) uri of remote image or array of remote uri strings |
options |
Object |
(Optional) custom options for the fetch image http request eg. {headers:{}, body:{}}
|
import { CacheManager } from '@georstat/react-native-image-cache';
const url = "https://..../image.jpg"
const urls = ["https://..../image.jpg", "https://..../image2.jpg", "https://..../image3.jpg"]
CacheManager.prefetch(url); // prefetch single image
CacheManager.prefetch(urls); // prefetch mutliple images
Clear local cache:
import { CacheManager } from '@georstat/react-native-image-cache';
await CacheManager.clearCache();
Remove single cache entry:
const uri = 'https://.../example.jpg';
await CacheManager.removeCacheEntry(uri);
Get local cache size:
await CacheManager.getCacheSize();
Check if image is cached:
await CacheManager.isImageCached(uri);
Props
CachedImage
accepts the following props:
Properties | PropType | Description |
---|---|---|
source |
String |
(Required) Uri of remote image. |
sourceAnimationDuration |
Number |
source image animation duration when loading, defaults to 1000 ms (overrides config) |
thumbnailSource |
String |
(Required) Uri of the thumbnail image |
thumbnailAnimationDuration |
Number |
Animation duration for thumbnail, defaults to 1000 ms (overrides config) |
blurRadius |
Number |
Amount of blur to apply on thumbnailSource image , defaults to 15 (overrides config) |
loadingImageComponent |
React.CompnentType |
Defaults to an image with the loadingSource prop |
noCache |
Boolean |
Do not cache the image, defaults to false witch means always cache the image |
maxAge |
Number |
Maximum age in hours to cache the image, defaults to undefined (infinite caching). Auto pruning won't take into consideration this value, it will delete the image anyway if the cacheLimit is reached
|
loadingImageStyle |
Object |
Style for loading image component. Works if you don't provide a loadingImageComponent
|
loadingSource |
object |
Source for loading Image component. Works if you don't provide loadingImageComponent
|
onError |
Func |
Runs when there is an error loading the image from cache |
onLoad |
Func |
Invoked when load completes successfully |
onLoadEnd |
Func |
Invoked when load either succeeds or fails |
resizeMode |
String |
React native Image component resizeMode defaults to contain
|
style |
Object |
source AND thumbnailSource image style |
options |
Object |
custom options for the fetch image http request eg. {headers:{}, body:{}}
|
accessibilityHint |
string |
accessibility hint for source (optional) |
accessibilityLabel |
string |
accessibility label for source (optional) |
accessibilityRole |
string |
accessibility role for source (optional, defaults to image ) |
accessibilityHintThumbnail |
string |
accessibility hint for thumbnailSource (optional) |
accessibilityLabelThumbnail |
string |
accessibility label for thumbnailSource (optional) |
accessibilityRoleThumbnail |
string |
accessibility role for thumbnailSource (optional, defaults to image ) |
accessibilityHintLoadingImage |
string |
accessibility hint for loadingSource (optional) |
accessibilityLabelLoadingImage |
string |
accessibility label for loadingSource (optional) |
accessibilityRoleLoadingImage |
string |
accessibility role for loadingSource (optional, defaults to image ) |
More info about React Native Accessibility
Blog Article about React Native Accessibility
Todo:
- [x] Convert library to React Hooks
- [x] Make
baseDir
configurable - [x] Delete single cache entry