ng-images-preview

v2.1.1

Published

2 months ago

🚀 High-performance Angular 18+ Image Preview & Gallery. Features native-like mobile gestures (Pinch-to-Zoom, Pull-to-Close), auto-thumbnails & smart preloading. Built with Signals & Zero-Dep Vanilla CSS.

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.
📡 Service API: Open previews programmatically via ImagesPreviewService without touching templates.
🧱 Gallery Component: Ready-to-use <ng-images-gallery> grid component.
🧩 Mixed Content: Support for mixing Images and TemplateRef (Videos, PDFs) in the same gallery.
🖼️ 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.
🖱️ PC Friendly: Mouse horizontal swipe navigation with inertia.
👆 Pull-to-Close: Drag down to close the preview (like native apps).
🎞️ Premium Transitions: Refined 400ms cubic-bezier easing for a high-end feel.
🎞️ Thumbnail Strip: Quick preview and navigation with an auto-scrolling strip.
🧩 Toolbar Extensions: Inject custom buttons (like Download) into the toolbar.
🤝 Hybrid Support: Fully compatible with both Standalone and NgModule-based apps.
⌨️ 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 and buffering for smoother 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 { }

Standalone (Recommended)

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

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

NgModule (Legacy Support)

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

@NgModule({
  imports: [NgImagesPreviewModule, ...]
})
export class AppModule {}

2. Cookbook / Usage Examples

A. Service-Based API (Programmatic)

Ideal for buttons, dynamic actions, or when you don't want to pollute your template with directives.

import { Component, inject } from '@angular/core';
import { ImagesPreviewService } from 'ng-images-preview';

@Component({ ... })
export class MyComponent {
  private previewService = inject(ImagesPreviewService);

  openGallery() {
    this.previewService.open('first.jpg', {
      images: ['first.jpg', 'second.jpg', 'third.jpg'], // Array of images
      initialIndex: 0, // Start at index 0
      showThumbnails: true
    });
  }
}

B. The Gallery Component (`<ng-images-gallery>`)

A ready-to-use responsive grid that handles the layout and click events for you.

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

@Component({
  imports: [ImagesGalleryComponent],
  template: `
    <ng-images-gallery 
      [images]="['img1.jpg', 'img2.jpg', 'img3.jpg']" 
      [columns]="3" 
      gap="10px">
    </ng-images-gallery>
  `
})
class MyComponent {}

C. Directive (The "classic" way)

Attach the preview behavior to any existing image or element.

<!-- Simple Single Image -->
<img src="small.jpg" ngImagesPreview>

<!-- Separate High-Res Source -->
<img src="small.jpg" [ngImagesPreview]="'huge-original.jpg'">

<!-- Gallery Mode on an Image -->
<img 
  src="thumb.jpg" 
  [ngImagesPreview]="'full.jpg'"
  [previewImages]="['full.jpg', 'other.jpg']">

D. Mixed Content (Images + Templates)

You can mix images with custom templates (like Video players) in the same gallery slide.

// In your component
@ViewChild('videoTpl') videoTpl: TemplateRef<any>;

openMixedGallery() {
  this.service.open('img1.jpg', {
    images: [
      'img1.jpg',
      this.videoTpl, // Use a TemplateRef here!
      'img3.jpg'
    ]
  });
}

3. Custom Template (Complete UI Override)

Take full control of the preview overlay UI.

<ng-template #myPreview let-state let-actions="actions">
  <div class="custom-overlay">
    <!-- Render content based on state -->
    <ng-container *ngIf="isTemplate(state.src)">
        <ng-container *ngTemplateOutlet="state.src"></ng-container>
    </ng-container>
    <img *ngIf="!isTemplate(state.src)" [src]="state.src">
    
    <button (click)="actions.zoomIn()">Zoom +</button>
    <button (click)="actions.close()">Close</button>
  </div>
</ng-template>

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

🌏 Server-Side Rendering (SSR)

This library is fully compatible with Angular Universal and SSR (Server-Side Rendering).

Safe DOM Access: All access to window, document, and body is guarded by isPlatformBrowser checks.
No Hydration Mismatches: The internal structure remains consistent between server and client.
Performance: The ImagesGalleryComponent uses NgOptimizedImage for LCP-friendly image loading.

⚙️ Configuration

Directive Inputs (`ImagesPreviewDirective`)

Component Inputs (`ImagesPreviewComponent`)

If you use the component directly:

Template Context (for Custom Templates)

When using previewTemplate, you get access to:

`state`

`actions`

CSS Variables (Theming)

You can customize the look and feel by overriding these CSS variables in your styles.css or component styles:

:root {
  /* Overlay */
  --ng-img-background: rgba(0, 0, 0, 0.95);
  --ng-img-text-color: rgba(255, 255, 255, 0.8);
  --ng-img-z-index: 50;
  
  /* Toolbar */
  --ng-img-toolbar-bg: rgba(255, 255, 255, 0.1);
  --ng-img-toolbar-hover: rgba(255, 255, 255, 0.2);
  --ng-img-gap: 16px;
  
  /* Thumbnails */
  --ng-img-thumb-strip-bg: rgba(0, 0, 0, 0.4);
  --ng-img-thumb-width: 60px;
  --ng-img-thumb-height: 40px;
  --ng-img-thumb-gap: 8px;
  --ng-img-thumb-border-radius: 6px;
  --ng-img-thumb-active-border: white;
  --ng-img-thumb-z-index: 55; /* Default is base + 5 */
  
  /* Misc */
  --ng-img-item-bg: rgba(0, 0, 0, 0.3);
}

🛠 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.