{"id":13808943,"url":"https://github.com/kfiroo/react-native-cached-image","last_synced_at":"2025-05-14T03:31:59.322Z","repository":{"id":43442896,"uuid":"75491322","full_name":"kfiroo/react-native-cached-image","owner":"kfiroo","description":"CachedImage component for react-native","archived":false,"fork":false,"pushed_at":"2022-03-02T04:44:54.000Z","size":5117,"stargazers_count":941,"open_issues_count":127,"forks_count":468,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-10-29T20:48:09.437Z","etag":null,"topics":["cache","image","images","react-native","react-native-component"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kfiroo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-12-03T18:08:13.000Z","updated_at":"2024-10-24T20:39:48.000Z","dependencies_parsed_at":"2022-08-22T20:40:45.307Z","dependency_job_id":null,"html_url":"https://github.com/kfiroo/react-native-cached-image","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kfiroo%2Freact-native-cached-image","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kfiroo%2Freact-native-cached-image/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kfiroo%2Freact-native-cached-image/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kfiroo%2Freact-native-cached-image/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kfiroo","download_url":"https://codeload.github.com/kfiroo/react-native-cached-image/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224917213,"owners_count":17391825,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cache","image","images","react-native","react-native-component"],"created_at":"2024-08-04T01:01:55.691Z","updated_at":"2024-11-19T00:31:14.789Z","avatar_url":"https://github.com/kfiroo.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# react-native-cached-image\n\nCachedImage component for react-native\n\nThis package is greatly inspired by [@jayesbe](https://github.com/jayesbe)'s amazing [react-native-cacheable-image](https://github.com/jayesbe/react-native-cacheable-image) but adds some functionality that we were missing when trying to handle caching images in our react-native app.\n\n## Installation\n\n    npm install react-native-cached-image --save\n    - or -\n    yarn add react-native-cached-image\n\nWe use [`react-native-fetch-blob`](https://github.com/wkh237/react-native-fetch-blob#installation) to handle file system access in this package and it requires an extra step during the installation.  \n\n_You should only have to do this once._\n\n    react-native link react-native-fetch-blob\n\nOr, if you want to add Android permissions to AndroidManifest.xml automatically, use this one:\n\n    RNFB_ANDROID_PERMISSIONS=true react-native link react-native-fetch-blob\n\n### Network Status - Android only\nAdd the following line to your android/app/src/AndroidManifest.xml\n\n    \u003cuses-permission android:name=\"android.permission.ACCESS_NETWORK_STATE\"/\u003e\n\n## Usage\n\nTODO - add usage example\n\n```jsx\nimport React from 'react';\nimport {\n    CachedImage,\n    ImageCacheProvider\n} from 'react-native-cached-image';\n\nconst images = [\n    'https://example.com/images/1.jpg',\n    'https://example.com/images/2.jpg',\n    'https://example.com/images/3.jpg',\n    // ...\n];\n\nexport default class Example extends React.Component {\n    render() {\n        return (\n            \u003cImageCacheProvider\n                urlsToPreload={images}\n                onPreloadComplete={() =\u003e console.log('hey there')}\u003e\n\n                \u003cCachedImage source={{uri: images[0]}}/\u003e\n\n                \u003cCachedImage source={{uri: images[1]}}/\u003e\n\n                \u003cCachedImage source={{uri: images[2]}}/\u003e\n\n            \u003c/ImageCacheProvider\u003e\n        );\n    }\n}\n```\n\n## API\n\nThis package exposes 3 modules:\n```jsx\nconst {\n    CachedImage,            // react-native component that is a drop-in replacement for your react-native `Image` components\n    ImageCacheProvider,     // a top level component that provides accsess to the underlying `ImageCacheManager` and preloads images\n    ImageCacheManager,      // the logic behind cache machanism - ttl, fs, url resolving etc. \n} = require('react-native-cached-image');\n```\n\n### ImageCacheManager\nThis is where all the cache magic takes place.\nThe API usually takes a *URL* and a set of [`ImageCacheManagerOptions`](#imagecachemanageroptions).\n\n#### `ImageCacheManager.downloadAndCacheUrl(url: String, options: ImageCacheManagerOptions): Promise\u003cString\u003e`\nCheck the cache for the the URL (after removing fixing the query string according to `ImageCacheManagerOptions.useQueryParamsInCacheKey`).\nIf the URL exists in cache and is not expired, resolve with the local cached file path.\nOtherwise, download the file to the cache folder, add it to the cache and then return the cached file path.\n\n#### `ImageCacheManager.seedAndCacheUrl(url: String, seedPath: String, options: ImageCacheManagerOptions): Promise\u003cString\u003e`\nCheck the cache for the the URL (after removing fixing the query string according to `ImageCacheManagerOptions.useQueryParamsInCacheKey`).\nIf the URL exists in cache and is not expired, resolve with the local cached file path.\nOtherwise, copy the seed file into the cache folder, add it to the cache and then return the cached file path.\n\n#### `ImageCacheManager.deleteUrl(url: String, options: ImageCacheManagerOptions): Promise`\nRemoves the cache entry for the URL and the local file corresponding to it, if it exists.\n\n#### `ImageCacheManager.clearCache(options: ImageCacheManagerOptions): Promise`\nClear the URL cache and remove files in the cache folder (as stated in the `ImageCacheManagerOptions.cacheLocation`)\n\n#### `ImageCacheManager.getCacheInfo(options: ImageCacheManagerOptions): Promise.\u003c{file: Array, size: Number}\u003e`\nReturns info about the cache, list of files and the total size of the cache.\n\n\n### CachedImage\n`CachedImage` is a drop in replacement for the `Image` component that will attempt to cache remote URLs for better performance.  \nIt's main use is to hide the cache layer from the user and provide a simple way to cache images.  \n`CachedImage` uses an instance of `ImageCacheManager` to interact with the cache, if there is an instance provided by `ImageCacheProvider` via the context it will be used, otherwise a new instance will be created with the options from the component's props. \n\n```jsx\n\u003cCachedImage\n    source={{\n        uri: 'https://example.com/path/to/your/image.jpg'\n    }}\n    style={styles.image}\n/\u003e\n```\n\n##### Props\n* `renderImage` - a function that returns a component, used to override the underlying `Image` component.\n* `activityIndicatorProps` - props for the `ActivityIndicator` that is shown while the image is downloaded.\n* `defaultSource` - prop to display a background image while the source image is downloaded. This will work even in android, but will not display background image if there you set borderRadius on this component style prop\n* `loadingIndicator` - _component_ prop to set custom `ActivityIndicator`.\n* `fallbackSource` - prop to set placeholder image. when `source.uri` is null or cached failed, the `fallbackSource` will be display.\n* any of the `ImageCacheManagerOptionsPropTypes` props - customize the `ImageCacheManager` for this specific `CachedImage` instance.\n\n### ImageCacheProvider\nThis is a top-level component with 2 major functions:\n1. Provide the customized `ImageCacheManager` to nested `CachedImage`.\n2. Preload a set of URLs.\n\n##### Props\n* `urlsToPreload` - an array of URLs to preload when the component mounts. default []\n* `numberOfConcurrentPreloads` - control the number of concurrent downloads, usually used when the `urlsToPreload` array is very big. default `urlsToPreload.length`\n* `onPreloadComplete` - callback for when the preload is complete and all images are cached.\n\n### ImageCacheManagerOptions\nA set of options that are provided to the `ImageCacheManager` and provide ways to customize it to your needs.\n\n```jsx\ntype ImageCacheManagerOptions = {\n    headers: PropTypes.object,                      // an object to be used as the headers when sending the request for the url. default {}\n    \n    ttl: PropTypes.number,                          // the number of seconds each url will stay in the cache. default 2 weeks\n    \n    useQueryParamsInCacheKey: PropTypes.oneOfType([ // when handling a URL with query params, this indicates how it should be treated:\n        PropTypes.bool,                             // if a bool value is given the whole query string will be used / ignored\n        PropTypes.arrayOf(PropTypes.string)         // if an array of strings is given, only these keys will be taken from the query string.\n    ]),                                             // default false\n    \n    cacheLocation: PropTypes.string,                // the path to the root of the cache folder. default the device cache dir \n    \n    allowSelfSignedSSL: PropTypes.bool,             // true to allow self signed SSL URLs to be downloaded. default false\n};\n\n```\n\n\n## Contributing\n\nPlease read [CONTRIBUTING.md](https://gist.github.com/PurpleBooth/b24679402957c63ec426) for details on our code of conduct, and the process for submitting pull requests to us.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkfiroo%2Freact-native-cached-image","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkfiroo%2Freact-native-cached-image","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkfiroo%2Freact-native-cached-image/lists"}