ngImagesPreview

A lightweight, modern, and accessible Image Preview library for Angular 18+, built with Signals and Vanilla CSS.

中文版 | English

🔗 Live Demo

Check out the component in action: https://lanxuexing.github.io/ng-images-preview/

✨ Features

• 🚀 Signals-Based: High performance and reactive by design.
• 🎨 Vanilla CSS: Zero dependencies, fully customizable via CSS variables.
• 🖼️ Multi-Image Gallery: Navigate through a list of images with arrows or swipe gestures.
• 📱 Mobile Ready: Swipe to navigate, double-tap to zoom, pinch-to-zoom gestures.
• ⌨️ Keyboard Support: Arrow keys to navigate, ESC to close.
• 🔍 Zoom & Pan: Smooth zooming and panning interactions.
• 🔄 Rotate & Flip: Built-in toolbar for image manipulation.
• 🧩 Custom Template: Complete control over the preview UI via ng-template.
• ♿ Accessible: ARIA labels and focus management.
• ⚡ Performance: Smart image preloading for smoother gallery navigation.
• 🌏 SSR Safe: Fully compatible with Angular Universal/SSR.
• 🌗 Dark Mode Ready: Inherits system preferences or app styles seamlessly.

📦 Installation

This component is available as an Angular Library.

npm install ng-images-preview

🚀 Quick Start

⚠️ Prerequisite: Enable Animations

This library relies on Angular animations. You must enable them in your application.

Standalone (app.config.ts):

import { provideAnimations } from '@angular/platform-browser/animations';

export const appConfig: ApplicationConfig = {
  providers: [provideAnimations()]
};

NgModule (app.module.ts):

import { BrowserAnimationsModule } from '@angular/platform-browser/animations';

@NgModule({
  imports: [BrowserAnimationsModule]
})
export class AppModule { }

1. Import Directive

Register ImagesPreviewDirective in your standalone component or module.

import { ImagesPreviewDirective } from 'ng-images-preview';

@Component({
  standalone: true,
  imports: [ImagesPreviewDirective, ...]
})
export class MyComponent {}

2. Basic Usage

Option A: Zero Config (Auto-detects source)

<!-- Direct usage on an img tag -->
<img src="small.jpg" ngImagesPreview>

<!-- Usage on a container (finds inner img) -->
<div ngImagesPreview><img src="small.jpg"></div>

Option B: Separate High-Res Source

<img src="small.jpg" [ngImagesPreview]="'huge-original.jpg'">

Option C: Gallery Mode Pass a list of images to previewImages to enable gallery navigation (arrows, swipe).

<img 
  src="item1.jpg" 
  [ngImagesPreview]="'item1-highres.jpg'"
  [previewImages]="['item1-highres.jpg', 'item2-highres.jpg', 'item3-highres.jpg']">

3. Custom Template

Take full control of the UI by providing a template.

<ng-template #myPreview let-state let-actions="actions">
  <div class="custom-overlay">
    <img [src]="state.src" [style.transform]="'scale(' + state.scale + ') rotate(' + state.rotate + 'deg)'">
    <button (click)="actions.zoomIn()">Zoom +</button>
    <button (click)="actions.close()">Close</button>
  </div>
</ng-template>

<img src="thumb.jpg" ngImagesPreview="large.jpg" [previewTemplate]="myPreview">

⚙️ Configuration

Directive Inputs (ImagesPreviewDirective)

| Property | Type | Default | Description | | :--- | :--- | :--- | :--- | | ngImagesPreview | string | '' | High-res URL. If empty, tries to read src from host or child img. | | previewImages | string[] | [] | List of image URLs for gallery navigation. | | previewTemplate | TemplateRef | undefined | Custom template to render instead of the default viewer. |

Component Inputs (ImagesPreviewComponent)

If you use the component directly:

| Property | Type | Default | Description | | :--- | :--- | :--- | :--- | | src | string | Required | The image source to display. | | images | string[] | [] | List of images for gallery. | | initialIndex | number | 0 | Initial image index in gallery. | | customTemplate | TemplateRef | undefined | Custom template for the overlay content. |

Template Context (for Custom Templates)

When using previewTemplate, you get access to:

state

| Property | Type | Description | | :--- | :--- | :--- | | src | string | Current image source. | | scale | number | Current zoom level (min: 0.5, max: 5). | | rotate | number | Rotation angle in degrees. | | flipH | boolean | Horizontal flip state. | | flipV | boolean | Vertical flip state. | | isLoading | boolean | True if image is loading. | | hasError | boolean | True if image failed to load. |

actions

| Method | Description | | :--- | :--- | | zoomIn() | Increase zoom level. | | zoomOut() | Decrease zoom level. | | rotateLeft() | Rotate -90 degrees. | | rotateRight() | Rotate +90 degrees. | | flipHorizontal() | Flip horizontally. | | flipVertical() | Flip vertically. | | reset() | Reset all transformations. | | close() | Close the preview. | | next() | Go to next image (if gallery). | | prev() | Go to previous image (if gallery). |

🛠 Development

This repository is structured as an Angular Workspace.

• Library Path: projects/ng-images-preview
• Demo Path: projects/demo

Scripts

• npm start: Run the demo application.
• npm run build:lib: Build the library for production.
• npm run build:demo: Build the demo application.
• npm test: Run unit tests.
• npm list: Run linting.

Built with ❤️ for the Angular Community.