smart-picture v0.1.0

Smart Picture

A simple Angular library to lazy load images, make responsive images, and use next generation formats.

This library features:

• Lazy loading of images
• Usage of HTML5's picture element
• Responsive image based on custom aspect ratio

Install

Angular 9+

$ npm install --save smart-picture

Import

The first thing you need to do after installing the library is importing the SmartPictureModule on any Angular module you want.

For example:

app.module.ts

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

import { SmartPictureModule } from 'smart-picture';

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule, SmartPictureModule],
  bootstrap: [AppComponent],
})
export class AppModule {}

After that you can start using the ng-smart-picture element on any component inside that module.

Usage

There are two ways of loading an image using the <ng-smart-picture></ng-smart-picture> custom element.

• Binding a SmartPictureSettings object.
• Binding individual setting values.

You can also use both methods at the same time, just keep in mind that the SmartPictureSettings object is going to overwrite any individual binding of the same setting.

Binding a SmartPictureSettings object.

For this method you need to pass to each <ng-smart-picture></ng-smart-picture> element a SmartPictureSettings object.

For example:

app.component.ts

import { Component } from '@angular/core';
import { SmartPictureSettings } from 'smart-picture';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss'],
})
export class AppComponent {
  public exampleImage: SmartPictureSettings = {
    src: {
      url: 'https://picsum.photos/seed/exampleImage/800/600.jpg',
      type: 'image/jpeg',
    },
  };
}

app.component.html

<ng-smart-picture [settings]="exampleImage"></ng-smart-picture>

A SmartPictureSettings object with all settings looks like this:

const exampleWithAllSettings: SmartPictureSettings = {
  src: {
    url: 'https://picsum.photos/seed/exampleImage/800/600.webp',
    type: 'image/webp',
    fallbackUrl: 'https://picsum.photos/seed/exampleImage/800/600.jpg',
    fallbackType: 'image/jpeg',
  },
  alt: 'An example image',
  ariaHidden: false,
  lazyLoad: true,
  heightRatio: 1,
  widthRatio: 1,
  objectFit: 'cover',
  objectPosition: 'center',
};

Binding individual setting values

If you can't or don't want to have a SmartPictureSettings object you can also bind individual setting values.

For example:

app.component.html

<ng-smart-picture src="https://picsum.photos/seed/exampleImage/800/600.jpg" type="image/jpeg"></ng-smart-picture>

A ng-smart-picture element with all setting properties looks like:

<ng-smart-picture
  src="https://picsum.photos/seed/exampleImage/800/600.webp"
  type="image/webp"
  fallbackSrc="https://picsum.photos/seed/exampleImage/800/600.jpg"
  fallbackType="image/jpeg"
  alt="An example image"
  [ariaHidden]="true"
  [lazyLoad]="true"
  [heightRatio]="1"
  [widthRatio]="1"
  objectFit="cover"
  objectPosition="center"
></ng-smart-picture>

ℹ️ Almost all attributes have the same name as the properties of the SmartPictureSettings object with the exception of src.url, src.type, src.fallbackUrl and src.fallbackType which correspond to src, type, fallbackSrc and fallbackType respectively.

Settings

The SmartPictureSettings interface

You can import the interface like this:

import { SmartPictureSettings } from 'smart-picture';

This interface has the following structure:

interface SmartPictureSettings {
  src?: {
    url: string;
    type: MIMEType;
    fallbackUrl?: string;
    fallbackType?: MIMEType;
  };
  alt?: string;
  ariaHidden?: boolean;

  lazyLoad?: boolean;

  heightRatio?: number;
  widthRatio?: number;

  objectFit?: ObjectFitValues;
  objectPosition?: string; // See https://developer.mozilla.org/es/docs/Web/CSS/object-position for more information
}

// See https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types for more information
type MIMEType =
  | 'image/jpeg'
  | 'image/apng'
  | 'image/bmp'
  | 'image/gif'
  | 'image/x-icon'
  | 'image/jpeg'
  | 'image/png'
  | 'image/svg+xml'
  | 'image/tiff'
  | 'image/webp';

// See https://developer.mozilla.org/es/docs/Web/CSS/object-fit for more information
export type ObjectFitValues = 'fill' | 'contain' | 'cover' | 'none' | 'scale-down' | 'inherit' | 'initial' | 'unset';

The pictureLoaded event

This event is fired every time a picture loads and is usefull if you want to run some code after a lazy loaded image load.

First you need to make a method on your component that will run every time a image with the event attached loads.

import { Component } from '@angular/core';
import { PictureLoadEvent } from 'smart-picture';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss'],
})
export class AppComponent {
  public onPictureLoaded(event: PictureLoadEvent): void {
    // here goes your code
  }
}

Then attach the method to the pictureLoaded event like this:

<ng-smart-picture
  src="https://picsum.photos/seed/exampleImage/800/600.webp"
  type="image/webp"
  [lazyLoad]="true"
  (pictureLoaded)="onPictureLoaded($event)"
></ng-smart-picture>

This will run the function onPictureLoaded() when the image loads and pass the PictureLoadEvent to the function.

The PictureLoadEvent is an object with the following structure:

interface PictureLoadEvent {
  wasLazyLoaded: boolean; // is true if the image was lazy loaded and false if it was not or if the browser does not support the IntersectionObserver API
  settings: SmartPictureSettings;
}

Binding source elements for the picture element

By default every ng-smart-picture element will have inside a pictureelement and if you need to pass asourceelement child ofpictureyou can just put it inside theng-smart-picture` like this.

<ng-smart-picture src="https://picsum.photos/seed/exampleImage/800/800.webp" type="image/webp">
  <source srcset="https://picsum.photos/seed/exampleImage2/600/600.webp" type="image/webp" media="(min-width: 600px)" />
</ng-smart-picture>

For more information about the source and picture element visit the <picture> documentation.