📷 ngx-smart-image-viewer

A lightweight, customizable Angular image viewer with support for zoom, rotate, fullscreen, drag, keyboard navigation, and custom action buttons. Compatible with Angular 16+ (strict & standalone supported).

✨ Features

🔍 Zoom in / zoom out

🔄 Rotate clockwise & counter-clockwise

🖱️ Mouse drag / pan

🖱️ Mouse wheel zoom (optional)

⌨️ Keyboard navigation (← →)

🖥️ Fullscreen support (via screenfull)

⏮️ ⏭️ Previous / Next navigation

🎛️ Config-driven buttons & icons

🧩 Custom action buttons

✅ Angular strict mode compatible

📦 Installation

npm install ngx-smart-image-viewer

Also install fullscreen dependency:

npm install screenfull

🧩 Usage

Basic Example

<ngx-smart-image-viewer
  [src]="images"
  [(index)]="currentIndex"
  [config]="viewerConfig">
</ngx-smart-image-viewer>

images: string[] = [
  'assets/img1.jpg',
  'assets/img2.jpg',
  'assets/img3.jpg'
];

currentIndex = 0;

viewerConfig = {
  allowFullscreen: true,
  zoomFactor: 0.1
};

⚙️ Set up

To use default configuration, simply import the SmartImageViewerComponent into your module, like so:

import { SmartImageViewerComponent } from "ngx-smart-image-viewer";
 
@NgModule({
  //...
  imports: [
    //...
    SmartImageViewerComponent
  ],
  //...
})

⚙️ Configuration (ImageViewerConfig)

export interface ImageViewerConfig {
  btnClass?: string;
  zoomFactor?: number;
  containerBackgroundColor?: string;
  wheelZoom?: boolean;
  allowFullscreen?: boolean;
  allowKeyboardNavigation?: boolean;

  btnShow?: {
    zoomIn?: boolean;
    zoomOut?: boolean;
    rotateClockwise?: boolean;
    rotateCounterClockwise?: boolean;
    next?: boolean;
    prev?: boolean;
  };

  btnIcons?: {
    zoomIn?: string;
    zoomOut?: string;
    rotateClockwise?: string;
    rotateCounterClockwise?: string;
    next?: string;
    prev?: string;
    fullscreen?: string;
  };

  customBtns?: Array<{
    name: string;
    icon: string;
  }>;
}

🎛️ Default Configuration

const DEFAULT_CONFIG = {
  btnClass: 'default',
  zoomFactor: 0.1,
  containerBackgroundColor: '#ccc',
  wheelZoom: false,
  allowFullscreen: true,
  allowKeyboardNavigation: true,
  btnShow: {
    zoomIn: true,
    zoomOut: true,
    rotateClockwise: true,
    rotateCounterClockwise: true,
    next: true,
    prev: true
  },
  btnIcons: {
    zoomIn: 'fa fa-plus',
    zoomOut: 'fa fa-minus',
    rotateClockwise: 'fa fa-repeat',
    rotateCounterClockwise: 'fa fa-undo',
    next: 'fa fa-arrow-right',
    prev: 'fa fa-arrow-left',
    fullscreen: 'fa fa-arrows-alt'
  }
};

🖥️ Fullscreen Support

Fullscreen is handled via a directive:

<div [ngxToggleFullscreen]="fullscreen">

Make sure screenfull is installed:

npm install screenfull

🎯 Custom Buttons

viewerConfig = {
  customBtns: [
    { name: 'download', icon: 'fa fa-download' },
    { name: 'info', icon: 'fa fa-info-circle' }
  ]
};

Listen to events:

<ngx-smart-image-viewer
  [src]="images"
  (customEvent)="handleCustomEvent($event)">
</ngx-smart-image-viewer>

handleCustomEvent(event: CustomEvent) {
  console.log(event.name, event.imageIndex);
}

⌨️ Keyboard Controls Key Action ← Previous image → Next image

Enabled when allowKeyboardNavigation: true.

🧱 Angular Compatibility

Angular Version Status 16 ✅ Supported 17 ✅ Supported 18 ✅ Supported 19 ✅ Supported