Nuclear Powered Marshmallows

    TypeScript icon, indicating that this package has built-in type declarations

    5.0.10 • Public • Published

    npm npm

    Ionic Image Loader

    Ionic Module that loads images in a native background thread and caches them for later use. Uses cordova-plugin-file and cordova-plugin-file-transfer via ionic-native wrappers.


    • Downloads images via a native thread. Images will download faster and they will not use the Webview's resources.
    • 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.
    • Shows a loading spinner while the images are loading. (can be disabled)
    • Allows setting maximum cache age to delete old images automatically. This is optional and disabled by default.
    • 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.
    • Allows setting a fallback image to be displayed in case the image you're trying to show doesn't exist on the web. (optional)
    • Works with the WKWebView Engine (iOS), as the images are copied to the temporary directory, which is accessible form within the WebView


    View our example project here:


    1. Install the NPM Package

    npm install --save ionic-image-loader

    2. Install Required Plugins

    npm i --save @ionic-native/file
    ionic cordova plugin add cordova-plugin-file
    npm i --save @ionic-native/file-transfer
    ionic cordova plugin add cordova-plugin-file-transfer

    3. Import IonicImageLoader module

    Add IonicImageLoader.forRoot() in your app's root module

    import { IonicImageLoader } from 'ionic-image-loader';
    // import the module
    export class AppModule {}

    Then add IonicImageLoader in your child/shared module(s)

    import { IonicImageLoader } from 'ionic-image-loader';
    export class SharedModule {}


    Basic Usage

    This HTML code demonstrates basic usage of this module:

    <img-loader src=""></img-loader>

    By default, the module sets the image as the background of the <img-loader> element. If you want the module to use the image as an <img> tag inside the <img-loader> elemen, just add useImg attribute as shown below:

    <img-loader src="" useImg></img-loader>

    You can also listen to the load event to be notified when the image has been loaded:

    <img-loader src="path/to/image" (load)="onImageLoad($event)></img-loader>
    import { ImgLoader } from 'ionic-image-loader';
    onImageLoad(imgLoaderImgLoader) {
      // do something with the loader

    Advanced Usage

    The <img-loader> component takes many attributes that allows you to customize the image. You can use the following table as a reference:

    Attribute Name Type Description Default Value
    src string The image URL N/A
    fallback string Fallback image url to load in case the original image fails to load N/A
    spinner boolean Show a spinner while the image loads true
    useImg boolean Use <img> tag to display the image in false
    width string The width of the image. This is ignored if useImg is set to true. 100%
    height string The height of the image. This is ignored if useImg is set to true. 100%
    display string Sets the display CSS property of the <img-loader> element. This is ignored if useImg is set to true. block
    backgroundSize string Sets the background-size CSS property of the <img-loader> element. This is ignored if useImg is set to true. contain
    backgroundRepeat string Sets the background-repeat CSS property of the <img-loader> element. This is ignored if useImg is set to true. no-repeat
    fallbackAsPlaceholder boolean Use fallback as a placeholder until the image loads. false

    Note: The default values can be changed using the global configuration feature.

    Global Configuration

    This is optional but it is helpful if you wish to set the global configuration for all of your <img-loader> instances. To configure the module, inject the ImageLoaderConfig provider in your app's main component.

    import { ImageLoaderConfig } from 'ionic-image-loader';
    export class MyMainAppComponent {
        private imageLoaderConfig: ImageLoaderConfig // optional, if you wish to configure the service 
        // disable spinners by default, you can add [spinner]="true" to a specific component instance later on to override this
        // set the maximum concurrent connections to 10

    Below are all the methods that the config provider has:


    Enables debug mode to receive console logs, errors, warnings.


    // enable debug mode to get console errors/warnings/logs
    // this could be useful while trying to debug issues with the component

    enableSpinner(enable: boolean)

    Sets the cache directory name. Defaults to 'image-loader-cache'. Defaults to true.


    this.imageLoaderConfig.enableSpinner(false); // disable spinner by default

    setHeight(height: string)

    Set default height for images that are not using tag. Defaults to 100%.

    setWidth(width: string)

    Set default width for images that are not using tag. Defaults to 100%.


    this.imageLoaderConfig.setWidth('500px'); // set default width to 500px

    setDisplay(display: string)

    Enable display mode for images that are not using tag. Defaults to block.



    useImageTag(use: boolean)

    Use tag by default.


    this.imageLoaderConfig.useImageTag(true); // use `<img>` tag by default

    setBackgroundSize(backgroundSize: string)

    Set default background size for images that are not using tag. Defaults to contain.



    setBackgroundRepeat(backgroundRepeat: string)

    Set background repeat for images that are not using tag. Defaults to no-repeat.



    setFallbackUrl(fallbackUrl: string)

    Set fallback URL to use when image src is undefined or did not resolve. This image will not be cached. This should ideally be a locally saved image.


    this.imageLoaderConfig.setFallbackUrl('assets/fallback.png'); // if images fail to load, display this image instead

    setCacheDirectoryName(directoryName: string)

    Set a custom directory name to store the cached images in. The cache directory by default is named image-loader-cache.



    setConcurrency(concurrency: number)

    Set the maximum number of concurrent connections. Cached images will be loaded instantly, this limit is only for new images.


    this.imageLoaderConfig.setConcurrency(5); // 5 concurrent connections

    setMaximumCacheSize(cacheSize: number)

    Sets the maximum cache size in bytes.


    this.imageLoaderConfig.setMaximumCacheSize(20 * 1024 * 1024); // set max size to 20MB

    setMaximumCacheAge(cacheAge: number)

    Sets the maximum allowed cache age in milliseconds


    this.imageLoaderConfig.setMaximumCacheAge(7 * 24 * 60 * 60 * 1000); // 7 days

    setImageReturnType(imageReturnType: string)

    Set 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'.



    enableFallbackAsPlaceholder(enable: boolean)

    Enable/Disable the fallback image as placeholder instead of the spinner. Defaults to false.



    setFileTransferOptions(options: any)

    Set options for FileTransfer plugin to use. If you would like to set a value for the trustAllHosts param, you can add it to the options object.


      trustAllHosts: true, // defaults to false
      headers: {
        Authorization: 'Basic dGVzdHVzZXJuYW1lOnRlc3RwYXNzd29yZA=='

    Preloading images

    import { ImageLoader } from 'ionic-image-loader';
    class MyComponent {
      constructor(imageLoader: ImageLoader) {

    Clearing the cache

    import { ImageLoader } from 'ionic-image-loader';
    class MyComponent {
      constructor(imageLoader: ImageLoader) {


    • Having an issue? or looking for support? Open an issue and we will get you the help you need.
    • Got a new feature or a bug fix? Fork the repo, make your changes, and submit a pull request.

    Support this project

    If 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 😄


    npm i ionic-image-loader-wxl

    DownloadsWeekly Downloads






    Unpacked Size

    141 kB

    Total Files


    Last publish


    • avatar