{"id":13697019,"url":"https://github.com/zyra/ionic-image-loader","last_synced_at":"2025-04-09T05:06:06.848Z","repository":{"id":11816092,"uuid":"70659082","full_name":"zyra/ionic-image-loader","owner":"zyra","description":"Ionic 2+ Component that loads images in a background thread and caches them for later use","archived":false,"fork":false,"pushed_at":"2022-12-02T11:46:25.000Z","size":3668,"stargazers_count":434,"open_issues_count":83,"forks_count":136,"subscribers_count":30,"default_branch":"master","last_synced_at":"2025-04-02T03:16:18.393Z","etag":null,"topics":["ionic"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/zyra.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-10-12T03:29:40.000Z","updated_at":"2024-12-11T12:57:09.000Z","dependencies_parsed_at":"2023-01-13T16:41:07.287Z","dependency_job_id":null,"html_url":"https://github.com/zyra/ionic-image-loader","commit_stats":null,"previous_names":["zyramedia/ionic-image-loader"],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zyra%2Fionic-image-loader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zyra%2Fionic-image-loader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zyra%2Fionic-image-loader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zyra%2Fionic-image-loader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zyra","download_url":"https://codeload.github.com/zyra/ionic-image-loader/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247980835,"owners_count":21027808,"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":["ionic"],"created_at":"2024-08-02T18:00:51.657Z","updated_at":"2025-04-09T05:06:06.807Z","avatar_url":"https://github.com/zyra.png","language":"TypeScript","readme":"[![npm](https://img.shields.io/npm/l/ionic-image-loader.svg)](https://www.npmjs.com/package/ionic-image-loader/)\n[![npm](https://img.shields.io/npm/dt/ionic-image-loader.svg)](https://www.npmjs.com/package/ionic-image-loader)\n[![npm](https://img.shields.io/npm/dm/ionic-image-loader.svg)](https://www.npmjs.com/package/ionic-image-loader)\n\n# Ionic Image Loader\n**Ionic** Module that loads images in a background thread and caches them for later use. Uses `HttpClient` from `Angular 4+`, and `cordova-plugin-file` via [`ionic-native`](https://github.com/driftyco/ionic-native) wrappers.\n\n\n## Features\n- Downloads images via a **native thread**. Images will download faster and they will not use the Webview's resources.\n- **Caches images** for later use. Images will be show up instantly the next time you display them since they're already saved on the local storage.\n- Shows a **loading spinner** while the images are loading. (can be disabled)\n- Allows setting **maximum cache age** to delete old images automatically. This is optional and **disabled by default**.\n- Allows setting **maximum cache size** to control how much space your app takes out of the users' phones. This is optional and **disabled by default**.\n- Allows setting a **fallback image** to be displayed in case the image you're trying to show doesn't exist on the web. (optional)\n- Works with the **[WKWebView Engine](https://github.com/apache/cordova-plugin-wkwebview-engine)** (iOS), as the images are copied to the temporary directory, which is accessible form within the WebView\n\n![Gif](https://github.com/ihadeed/ionic-image-loader-example/blob/master/gif.gif?raw=true)\n\nView our example project here: https://github.com/zyramedia/ionic-image-loader-example\n\n- [Installation](https://github.com/zyramedia/ionic-image-loader#installation)\n- [Usage](https://github.com/zyramedia/ionic-image-loader#usage)\n  - [Basic usage](https://github.com/zyramedia/ionic-image-loader#basic-usage)\n  - [Advanced Usage](https://github.com/zyramedia/ionic-image-loader#advanced-usage)\n- [Global Configuration](https://github.com/zyramedia/ionic-image-loader#global-configuration)\n\n\n## Installation\n\n#### 1. Install the NPM Package\n```\nnpm install --save ionic-image-loader\n```\n\n#### 2. Install Required Plugins\n```\nnpm i --save @ionic-native/file\nionic cordova plugin add cordova-plugin-file\n```\n\n#### 3. Import `IonicImageLoader` module\n\n**Add `IonicImageLoader.forRoot()` in your app's root module**\n```typescript\nimport { IonicImageLoader } from 'ionic-image-loader';\n\n// import the module\n@NgModule({\n  ...\n  imports: [\n    IonicImageLoader.forRoot()\n  ]\n})\nexport class AppModule {}\n```\n\n**Then add `IonicImageLoader` in your child/shared module(s)**\n```typescript\nimport { IonicImageLoader } from 'ionic-image-loader';\n\n@NgModule({\n  ...\n  imports: [\n    IonicImageLoader\n  ]\n})\nexport class SharedModule {}\n```\n\n# Usage\n\n## Basic Usage\nThis HTML code demonstrates basic usage of this module:\n```html\n\u003cimg-loader src=\"https://path.to/my/image.jpg\"\u003e\u003c/img-loader\u003e\n```\n\nBy default, the module sets the image as the background of the `\u003cimg-loader\u003e` element. If you want the module to use the image as an `\u003cimg\u003e` tag inside the `\u003cimg-loader\u003e` element, just add `useImg` attribute as shown below:\n```html\n\u003cimg-loader src=\"https://path.to/my/image.jpg\" useImg\u003e\u003c/img-loader\u003e\n```\n\nYou can also listen to the load event to be notified when the image has been loaded:\n```html\n\u003cimg-loader src=\"path/to/image\" (load)=\"onImageLoad($event)\u003e\u003c/img-loader\u003e\n```\n```typescript\nimport { ImgLoaderComponent } from 'ionic-image-loader';\n\n...\n\nonImageLoad(imgLoader: ImgLoaderComponent) {\n  // do something with the loader\n}\n```\n\n## Advanced Usage\nThe `\u003cimg-loader\u003e` component takes many attributes that allows you to customize the image. You can use the following table as a reference:\n\n| Attribute Name | Type | Description | Default Value |\n| --- | --- | --- | --- |\n| src | string | The image URL | N/A |\n| fallbackUrl | string | Fallback image url to load in case the original image fails to load | N/A |\n| spinner | boolean | Show a spinner while the image loads | true |\n| useImg | boolean | Use `\u003cimg\u003e` tag to display the image in | false |\n| width | string | The width of the image. This is ignored if `useImg` is set to `true`. | 100% |\n| height | string | The height of the image. This is ignored if `useImg` is set to `true`. | 100% |\n| display | string | Sets the `display` CSS property of the `\u003cimg-loader\u003e` element. This is ignored if `useImg` is set to `true`. | block |\n| backgroundSize | string | Sets the `background-size` CSS property of the `\u003cimg-loader\u003e` element. This is ignored if `useImg` is set to `true`. | contain |\n| backgroundRepeat | string | Sets the `background-repeat` CSS property of the `\u003cimg-loader\u003e` element. This is ignored if `useImg` is set to `true`. | no-repeat |\n| fallbackAsPlaceholder | boolean | Use fallback as a placeholder until the image loads. | false |\n| imgAttributes | ImageAttribute[] | An array of ImageAttribute objects (element, value).  If `useImg == true`, this array will be iterated and each object added as an attribute to the generated `\u003cimg\u003e` HTML element. | []] |\n\n\n**Note:** The default values can be changed using the [global configuration](https://github.com/zyramedia/ionic-image-loader#global-configuration) feature.\n\n## Quirks\nIn some cases, images won't load on the first time, the culprit seems to be `@ionic-native/file` or `cordova-plugin-file` in its `writeFile` function not calling resolve or reject.\n\nIn the meantime we find a solution, here's a quick workaround:\n\nIn **./src/index.html** move your `polyfill.js`include above `cordova.js`\n```\n    \u003c!-- The polyfills js is generated during the build process --\u003e\n    \u003cscript src=\"build/polyfills.js\"\u003e\u003c/script\u003e\n\n    \u003c!-- cordova.js required for cordova apps (remove if not needed) --\u003e\n    \u003cscript src=\"cordova.js\"\u003e\u003c/script\u003e\n```\n\n# Global Configuration\nThis is optional but it is helpful if you wish to set the global configuration for all of your `\u003cimg-loader\u003e` instances. To configure the module, inject the `ImageLoaderConfig` provider in your app's main component.\n```typescript\nimport { ImageLoaderConfig } from 'ionic-image-loader';\n@Component({\n...\n})\nexport class MyMainAppComponent {\n  \n  constructor(\n    private imageLoaderConfig: ImageLoaderConfig // optional, if you wish to configure the service \n  ){\n    \n    // disable spinners by default, you can add [spinner]=\"true\" to a specific component instance later on to override this\n    imageLoaderConfig.enableSpinner(false);\n    \n    // set the maximum concurrent connections to 10\n    imageLoaderConfig.setConcurrency(10);\n  }\n  \n}\n```\n\nBelow are all the methods that the config provider has:\n\n#### enableDebugMode() \nEnables debug mode to receive console logs, errors, warnings.\n\nExample:\n```typescript\n// enable debug mode to get console errors/warnings/logs\n// this could be useful while trying to debug issues with the component\nthis.imageLoaderConfig.enableDebugMode();\n```\n---\n#### enableSpinner(enable: boolean)\nSets the cache directory name. Defaults to 'image-loader-cache'. Defaults to `true`.\n\nExample:\n```typescript\nthis.imageLoaderConfig.enableSpinner(false); // disable spinner by default\n```\n\n---\n#### setHeight(height: string)\nSet default height for images that are not using \u003cimg\u003e tag. Defaults to `100%`.\n\n---\n#### setWidth(width: string)\nSet default width for images that are not using \u003cimg\u003e tag. Defaults to `100%`.\n\nExample:\n```typescript\nthis.imageLoaderConfig.setWidth('500px'); // set default width to 500px\n```\n\n---\n#### setDisplay(display: string)\nEnable display mode for images that are not using \u003cimg\u003e tag. Defaults to `block`.\n\nExample:\n```typescript\nthis.imageLoaderConfig.setDisplay('inline-block');\n```\n---\n#### useImageTag(use: boolean)\nUse \u003cimg\u003e tag by default.\n\nExample:\n```typescript\nthis.imageLoaderConfig.useImageTag(true); // use `\u003cimg\u003e` tag by default\n```\n\n---\n#### setBackgroundSize(backgroundSize: string)\nSet default background size for images that are not using \u003cimg\u003e tag. Defaults to `contain`.\n\nExample:\n```typescript\nthis.imageLoaderConfig.setBackgroundSize('cover');\n```\n---\n#### setBackgroundRepeat(backgroundRepeat: string)\nSet background repeat for images that are not using \u003cimg\u003e tag. Defaults to `no-repeat`.\n\nExample:\n```typescript\nthis.imageLoaderConfig.setBackgroundRepeat('repeat-x');\n```\n---\n\n#### setFallbackUrl(fallbackUrl: string)\nSet fallback URL to use when image src is undefined or did not resolve.\nThis image will not be cached. This should ideally be a locally saved image.\n\nExample:\n```typescript\nthis.imageLoaderConfig.setFallbackUrl('assets/fallback.png'); // if images fail to load, display this image instead\n```\n\n---\n#### setCacheDirectoryName(directoryName: string)\nSet a custom directory name to store the cached images in. The cache directory by default is named `image-loader-cache`.\n\nExample:\n```typescript \nthis.imageLoaderConfig.setCacheDirectoryName('my-custom-cache-directory-name');\n```\n---\n\n#### setConcurrency(concurrency: number)\nSet the maximum number of concurrent connections. Cached images will be loaded instantly, this limit is only for new images.\n\nExample:\n```typescript\nthis.imageLoaderConfig.setConcurrency(5); // 5 concurrent connections\n```\n---\n#### setMaximumCacheSize(cacheSize: number)\nSets the maximum cache size in bytes.\n\nExample: \n```typescript\nthis.imageLoaderConfig.setMaximumCacheSize(20 * 1024 * 1024); // set max size to 20MB\n```\n---\n#### setMaximumCacheAge(cacheAge: number)\nSets the maximum allowed cache age in milliseconds\n\nExample:\n```typescript\nthis.imageLoaderConfig.setMaximumCacheAge(7 * 24 * 60 * 60 * 1000); // 7 days\n```\n---\n#### setImageReturnType(imageReturnType: string)\nSet the return type of cached images. By default this option is set to 'uri', which will return the native file URL. If you want to get a base64-encoded representation of the file set the return type to 'base64'.\n\nExample:\n```typescript\nthis.imageLoaderConfig.setImageReturnType('base64');\n```\n---\n#### enableFallbackAsPlaceholder(enable: boolean)\nEnable/Disable the fallback image as placeholder instead of the spinner. Defaults to false.\n\nExample:\n```ts\nthis.imageLoaderConfig.enableFallbackAsPlaceholder(true);\n```\n---\n#### setHttpHeaders(headers: HttpHeaders)\nSet headers for HttpClient to use.\n\nExample:\n```ts\nconst headers = new HttpHeaders()\n                  .set(\"Authorization\", \"Basic dGVzdHVzZXJuYW1lOnRlc3RwYXNzd29yZA==\");\nthis.imageLoaderConfig.setHttpHeaders(headers);\n```\n---\n#### setFileNameCachedWithExtension(enable: boolean)\nEnable/Disable the save filename of cached images with extension.  Defaults to false.\n\nExample:\n```ts\nthis.imageLoaderConfig.setFileNameCachedWithExtension(true);\n```\n---\n#### setFallbackFileNameCachedExtension(extension: string)\nSometime url missing extension, in this case you can set fallback as default extension. Defaults to '.jpg'\n\nExample:\n```ts\nthis.imageLoaderConfig.setFallbackFileNameCachedExtension('.png');\n```\n---\n\n# Preloading images\n```typescript\nimport { ImageLoader } from 'ionic-image-loader';\n\nclass MyComponent {\n  \n  constructor(imageLoader: ImageLoader) {\n    imageLoader.preload('http://path.to/image.jpg');\n  }\n  \n}\n\n```\n\n# Clearing the cache\n```typescript\n\nimport { ImageLoader } from 'ionic-image-loader';\n\n@Component(...)\nclass MyComponent {\n  \n  constructor(imageLoader: ImageLoader) {\n    imageLoader.clearCache();\n  }\n  \n}\n\n```\n\n# Clearing single image cache\n```typescript\n\nimport { ImageLoader } from 'ionic-image-loader';\n\n@Component(...)\nclass MyComponent {\n  \n  constructor(imageLoader: ImageLoader) {\n    imageLoader.clearImageCache('http://path.to/image.jpeg');\n  }\n  \n}\n\n```\n\n# Passing HTML / CSS Attributes to a generated image\n\nWhen using ImageLoader to generate an `\u003cimg\u003e` element it may be desirable for the generated element to include additional attributes to provide styling or interaction qualities.  The optional `imgAttributes` value can be used to provide such additional attributes which will be included in the generated `\u003cimg\u003e` element in the DOM.\n\nUsage:\n\n1. Include the ImageAttribute model in your .ts\n```typescript\nimport { ImageAttribute } from 'ionic-image-loader'\n```\n\n2. Generate an array of ImageAttribute objects\n```typescript\nconst imageAttributes: ImageAttribute[] = [];\nimageAttributes.push({\n  element: 'class',\n  value: 'circle-photo'\n})\n```\n\n3. Include the `imgAttributes` element in the `img-loader` element of your HTML\n```html\n \u003cimg-loader [src]=\"...\" useImg [imgAttributes]=\"imageAttributes\"\u003e \u003c/img-loader\u003e\n```\n\n4. The generated `\u003cimg\u003e` tag will be rendered with the specified attributes\n```html\n  \u003cimg src=\"...\" class=\"circle-photo\"\u003e\n```\n\n\u003cbr\u003e\u003cbr\u003e\n## Contribution\n- **Having an issue**? or looking for support? [Open an issue](https://github.com/zyra/ionic-image-loader/issues/new) and we will get you the help you need.\n- Got a **new feature or a bug fix**? Fork the repo, make your changes, and submit a pull request.\n\n## Support this project\nIf you find this project useful, please star the repo to let people know that it's reliable. Also, share it with friends and colleagues that might find this useful as well. Thank you :smile:\n","funding_links":[],"categories":["UI"],"sub_categories":["Images"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzyra%2Fionic-image-loader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzyra%2Fionic-image-loader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzyra%2Fionic-image-loader/lists"}