# ngx-image-fallback

> Image fallback directive for img tag and background images on Angular (Angular 21, signal inputs, zoneless-safe)

Latest version **4.1.1** (published 2026-03-07) · MIT license · 0 weekly downloads

## Install

```sh
npm install ngx-image-fallback
pnpm add ngx-image-fallback
yarn add ngx-image-fallback
bun add ngx-image-fallback
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 4.1.1 |
| Published | 2026-03-07 |
| First published | 2021-11-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 30.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Joy Biswas |
| Maintainers | joyblanks |
| Keywords | angular, image, fallback, directive, default |

## Links

- npm: https://www.npmjs.com/package/ngx-image-fallback
- Repository: https://github.com/joyblanks/ngx-image-fallback
- Issues: https://github.com/joyblanks/ngx-image-fallback/issues
- npm.io page: https://npm.io/package/ngx-image-fallback

## Dependencies (1)

- [tslib](https://npm.io/package/tslib.md) ^2.3.0

## Alternatives

- [exif-parser](https://npm.io/package/exif-parser.md) — 3.8M weekly downloads
- [vite-plugin-compression](https://npm.io/package/vite-plugin-compression.md) — 569.5K weekly downloads
- [pica](https://npm.io/package/pica.md) — 442.4K weekly downloads
- [@reportportal/client-javascript](https://npm.io/package/@reportportal/client-javascript.md) — 408.8K weekly downloads
- [@tldraw/state](https://npm.io/package/@tldraw/state.md) — 316.0K weekly downloads

## Recent versions

- 4.1.1 (latest) — 2026-03-07
- 4.1.0 — 2026-03-07
- 4.0.0 — 2026-03-07
- 3.0.0 — 2026-03-07
- 2.0.0 — 2026-03-07
- 1.0.2 — 2021-11-14
- 1.0.1 — 2021-11-09
- 1.0.0 — 2021-11-09

## README

# Image Fallback Directive for Angular

[![Build Status](https://travis-ci.com/joyblanks/ngx-image-fallback.svg?branch=main)](https://travis-ci.com/joyblanks/ngx-image-fallback)
[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
[![Renovate enabled](https://img.shields.io/badge/renovate-enabled-brightgreen.svg)](https://renovatebot.com/)
[![npm version](https://badge.fury.io/js/ngx-image-fallback.svg)](https://npmjs.com/package/ngx-image-fallback)
[![GitHub version](https://badge.fury.io/gh/joyblanks%2Fngx-image-fallback.svg)](https://badge.fury.io/gh/joyblanks%2Fngx-image-fallback)



## Image fallback directive for img tag and background images on Angular
---



## Installation
```sh
npm i ngx-image-fallback -S
```

### SystemJS
In your ```system.config.js``` add to **map** and **packages**

```js
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)

```ts
// *.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
```ts
// *.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)
```html
<!-- *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)
```html
<!-- *.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)
```css
/* *.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);}
}
```

```html
<!-- *.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)
```html
<!-- *.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)
```ts
// 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';
}
```
```html
<!-- 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](https://tldrlegal.com/license/mit-license) © [Joy Biswas](https://github.com/joyblanks)

---
_Source: https://npm.io/package/ngx-image-fallback · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._