| Package | Angular | Install |
|---|---|---|
| 1.x | <11 | npm i ngx-image-fallback@^1 |
| 2.x | 11–15 | npm i ngx-image-fallback@^2 |
| 3.x | 16–18 | npm i ngx-image-fallback@^3 |
| 4.x | 19+ | npm i ngx-image-fallback@^4 |
- 4.x (recommended for new apps): Angular 19+, signal
input()/output(), zoneless-safe, works without zone.js. - 3.x: Standalone + NgModule,
inject(),@Input(). - 2.x: NgModule, Angular 11–15.
- 1.x: NgModule only, Angular <11.
# Angular 19+ (recommended)
npm i ngx-image-fallback@^4 -S
# Angular 16–18
npm i ngx-image-fallback@^3 -S
# Angular 11–15
npm i ngx-image-fallback@^2 -S
# Angular <11
npm i ngx-image-fallback@^1 -SIn 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' }
}// *.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 MyComponent {
image = 'https://example.com/photo.jpg';
fallback = '/assets/placeholder.png';
}Fallback as an array (4.x): You can pass multiple URLs; they are tried in order. If none load, the built-in data fallback image is shown.
// Try several fallbacks, then show built-in placeholder
fallback = ['/assets/backup1.png', '/assets/backup2.png', '/assets/placeholder.png'];
// Or a single string (same as before)
fallback = '/assets/placeholder.png';<img [src]="image" ngxImageFallback [ngxImageFallback]="fallback" />4.x is standalone-only (no NgModule). 3.x also provides NgxImageFallbackModule if you use modules.
4.x emits when fallback is used or the image loads:
<img
[src]="image"
ngxImageFallback
[ngxImageFallback]="fallback"
(fallbackUsed)="onFallback()"
(imageLoaded)="onLoaded()"
/>For Angular <11 through 18 you can use the module:
// *.module.ts (1.x, 2.x or 3.x)
import { NgModule } from '@angular/core';
import { NgxImageFallbackModule } from 'ngx-image-fallback';
@NgModule({
declarations: [AppComponent],
imports: [NgxImageFallbackModule, ...],
bootstrap: [AppComponent]
})
export class AppModule { }Basic Usage in component
// *.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
> </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')'"
> </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')'"
> </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')'"
> </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"
> </div> <!-- with a background image -->npm ci
npm run lint
npm run test
npm run buildTests use Vitest. Node version is defined in .nvmrc.
Releases are automated with GitHub Actions and semantic-release:
- Push to
mainwith conventional commits (e.g.fix:,feat:) runs the release workflow: lint → test → build, then publishes to npm and creates a GitHub release if the commit history warrants a new version. - Manual publish:
npm run publish:lib(builds and runsnpm publishfromdist/ngx-image-fallback). You must be logged in (npm login) and have set NPM_TOKEN in the repo if using CI.
CI setup: In GitHub → Settings → Secrets and variables → Actions, add NPM_TOKEN (create an automation token at npmjs.com/settings → Access Tokens).
TODO:
- Multiple background images
- Add a demo
- (4.x has
fallbackUsedandimageLoadedoutputs for fallback/load events)