Skip to content


Switch branches/tags

React Native Image Cache on File System with Progressive Loading

npm version npm downloads npm License: MIT GitHub package.json version Platform - Android and iOS

Inspired by:



If you're not using react-native-reanimated version 2.x.x then use version 1.x.x of this module

If you're looking for an image library with thumbnails visit @georstat/react-native-image-gallery






Custom Loading Image Component: (see example)




yarn add @georstat/react-native-image-cache


npm i @georstat/react-native-image-cache

link native packages:

 cd ios
 pod install


For react native >= 0.65 use react-native-file-access >= 2.0.0


Put this Global config on your app entry eg. App.tsx or index.js (Required):

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,

Custom cache key, useful for caching images from Amazon's S3 and similar services, add this (or whatever suits your needs) on CacheManager.config:

CacheManager.config = {
  // ...
  getCustomCacheKey: (source: string) => {
    // Remove params from the URL for caching images (useful for caching images from Amazons S3 bucket and etc)
    let newCacheKey = source;
    if (source.includes('?')) {
      newCacheKey = source.substring(0, source.lastIndexOf('?'));
    return newCacheKey;

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:

  1. Get all files from baseDir.
  2. Sort them by lastModified, oldest first.
  3. Get total size in Bytes by using reduce array method.
  4. Check total size from step 3 and subtract cacheLimit value.
  5. 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).
  6. 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.

Directory constants, choose wisely: (react-native-file-access docs)

  • Dirs.CacheDir
  • Dirs.DatabaseDir (Android only)
  • Dirs.DocumentDir
  • Dirs.LibraryDir (iOS only)
  • Dirs.MainBundleDir
  • Dirs.SDCardDir (Android only)
    • Prefer FileSystem.cpExternal() when possible.


import { CachedImage } from '@georstat/react-native-image-cache';

  style={{ height: 350, width: 150 }}

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

Prefetch Image and return blob/base64:

Accepts 2 parameters:

Parameter Type Description
image String (Required) uri of remote image
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"

 CacheManager.prefetchBlob(url).then(response => console.log(response)); // response is the base64 string

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);


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 1000ms (overrides config)
thumbnailSource String (Required) Uri of the thumbnail image
thumbnailAnimationDuration Number Animation duration for thumbnail, defaults to 1000ms (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 which 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
testID String testID, useful for tests
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


  • Convert library to React Hooks
  • Make baseDir configurable
  • Delete single cache entry