Image Fallback Directive for Angular

Image fallback directive for img tag and background images on Angular

Installation

npm i ngx-image-fallback -S

SystemJS

In your system.config.js add to map and packages

var map = {
  ...
  'ngx-image-fallback': 'node_modules/ngx-image-fallback/bundles'
}
var packages = {
  ...
  'ngx-image-fallback': { defaultExtension: 'js' }
}

Usage

Add the directive to your component or route imports (standalone)

// *.component.ts
import { Component } from '@angular/core';
import { NgxImageFallbackDirective } from 'ngx-image-fallback';

@Component({
  standalone: true,
  imports: [NgxImageFallbackDirective],
  template: '<img [src]="image" ngxImageFallback [ngxImageFallback]="fallback" />',
})
export class AppComponent {
  image = 'https://example.com/photo.jpg';
  fallback = '/assets/fallback.jpg';
}

Basic usage

// *.component.ts

import { Component } from '@angular/core';
 
@Component({
  selector: 'app-root',
  template: '<img [src]="an_image_that_might_be_unavailable" [ngxImageFallback]="fallback" />'
})
export class AppComponent {
  an_image_that_might_be_unavailable: string = 'https://invalidimage12345.com/unknown.jpg';
  fallback: string = '/assets/images/fallback.jpg';
}

Sample Usage 1: (Using built in default fallback image and default loader)

<!-- *component.html -->

<img 
  src="an_invalid_image" 
  ngxImageFallback 
/> <!-- with img tag -->

<div 
  [style.background-image]="an_invalid_image" 
  ngxImageFallback
>&nbsp;</div> <!-- with a background image -->

Sample Usage 2: (Using another image from web or assets library)

<!-- *.component.html -->

<img 
  src="an_invalid_image" 
  ngxImageFallback="/assets/images/fallback.png" 
/> <!-- with img tag -->

<div 
  [style.background-image]="an_invalid_image" 
  ngxImageFallback="'url('https://ssl.gstatic.com/gb/images/p2_772b9c3b.png')'"
>&nbsp;</div> <!-- with a background image -->

Sample Usage 3: (Using a loader while the image loads with success or fallback)

/* *.component.css */

.image-loader::after { /* 👈 Reference this class in [ngxImageFallbackStyles]="{loaderClass:'image-loader'}" */
  border-radius: 50%;
  height: 15px;
  max-height: 100%;
  border-top: 3px solid #ffff00;
  animation: 1s rotate linear infinite;
  content: " ";
  inset: 0;
  display: block;
  aspect-ratio: 1;
  margin: auto;
}
@keyframes rotate {
  from: {transform: rotate(0deg);}
  to: {transform: rotate(360deg);}
}

<!-- *.component.html -->

<img 
  src="an_invalid_image" 
  [ngxImageFallbackStyles]="{loaderClass:'image-loader'}"
  ngxImageFallback="https://ssl.gstatic.com/gb/images/p2_772b9c3b.png" 
/> <!-- with img tag and a loader class -->

<div 
  [style.background-image]="an_invalid_image" 
  [ngxImageFallbackStyles]="{loaderClass:'image-loader'}"
  ngxImageFallback="'url('https://ssl.gstatic.com/gb/images/p2_772b9c3b.png')'"
>&nbsp;</div> <!-- with a background image and a loader class -->

Sample Usage 4: (Using the default loader while the image loads with success or fallback, but with a different color)

<!-- *.component.html -->

<img 
  src="an_invalid_image" 
  [ngxImageFallbackStyles]="{loaderColor:'#ffffff'}"
  ngxImageFallback="https://ssl.gstatic.com/gb/images/p2_772b9c3b.png" 
/> <!-- with img tag and white colored default loader -->

<div 
  [style.background-image]="an_invalid_image" 
  [ngxImageFallbackStyles]="{loaderColor:'red'}"
  ngxImageFallback="'url('https://ssl.gstatic.com/gb/images/p2_772b9c3b.png')'"
>&nbsp;</div> <!-- with a background image and red colored default loader -->

Sample Usage 5: (Referencing attributes with binding)

// my-component.component.ts

@Component({
  selector: 'my-component',
  templateUrl: './my-component.component.html',
  styleUrls: ['./my-component.component.scss']
})
export class MyComponent {
  image: string = 'https://invalidimage12345.com/unknown.jpg';
  fallback: string = '/assets/images/fallback.jpg';
}

<!-- my-component.component.html -->

<img 
  [src]="image" 
  [ngxImageFallback]="fallback" 
/> <!-- with img tag -->

<div 
  [style.background-image]="'url('+image+')'" 
  [ngxImageFallback]="fallback"
>&nbsp;</div> <!-- with a background image -->

TODO:

• Multiple background images
• Event emitter to loaded original or fallback
• Add a demo

License

MIT © Joy Biswas