An Angular directive to efficiently lazy load images using the IntersectionObserver API.

🏠 Homepage

📝 Table of Contents

• Prerequisites
• Install
• Setup
• Usage
• Author
• Contributing
• Show your support
• License

✅ Prerequisites

The library uses IntersectionObserver API, Check its Browser Support and if you need to target unsupported browsers, you can use the official Polyfill. If you don't want to increase the bundle size by using the Polyfill, the library fallsback to delaying the image loading using setTimeout in an attempt to minimize render blocking.

The library is Server-Side Rendering (SSR) compatible and can be used normally with Angular Universal.

The library can used normally with Ionic, however it won't be very useful since Ionic provides its own lazy loaded image component ion-img, which you should definitely use instead.

⬇️ Install

Using npm

npm install --save @trendster-io/ng-lazy-image

Using yarn

yarn add @trendster-io/ng-lazy-image

🛠 Setup

Once installed you need to import our module in the parent module for the component you will be using it in:

import { LazyImageModule } from '@trendster-io/ng-lazy-image';

@NgModule({
  ...
  imports: [LazyImageModule, ...],
  ...
})
export class YourModule {
}

Usage

The directive is written to utilize a normal img tag so that you don't change your familiar markup for adding an image in HTML. To use it, just add a lazy attribute on the img element.

API

Properties

You can customize the IntersectionObserverOptions using their exact names as properties to the img:

• root: Element
• rootMargin: string
• threshold: number | number[]

Events

Listening to any of the events

• willLoad: Custom event, called whenever the image is going to start loading
• load: The native img load event, called whenever the image has finished loading
• error: The native img error event, called whenever the image failed to load

Example:

import { Component, OnInit, ElementRef } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <img src="assets/img/example1.jpg" alt="Example 1 Image" lazy (willLoad)="onImageWillLoad('Example 1)" (load)="onImageLoad('Example 1')" (error)="onImageError('Example 1')" />

    <img [src]="example2Image" lazy (willLoad)="onImageWillLoad('Example 2')" (load)="onImageLoad('Example 2')" (error)="onImageError('Example 2')" />

    <img src="assets/img/example3.jpg" alt="Example 3 Image" lazy [root]="rootElement" rootMargin="20px 10px 20px 10px" [threshold]="0.4" />
  `
})
class ExampleComponent implements OnInit {
  example2Image = 'https://via.placeholder.com/150';
  rootElement: Element;

  constructor(private el: ElementRef<Element>) {}

  ngOnInit(): void {
    this.rootElement = this.el.nativeElement;
  }

  onImageWillLoad(name: string): void {
    console.log(`Image ${name} Will Load`);
  }

  onImageLoad(name: string): void {
    console.log(`Image ${name} Loaded`);
  }

  onImageError(name: string): void {
    console.log(`Image ${name} Failed To Load`);
  }
}

Author

👤 Omar Doma

• Github: @omardoma

🤝 Contributing

Contributions, issues and feature requests are welcome!Feel free to check issues page.

Show your support

Give a ⭐️ if this project helped you!

📝 License

Copyright © 2019 Trendster. This project is MIT licensed.