π 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.
npm install ng-images-previewA lightweight, modern, and accessible Image Preview library for Angular 18+, built with Signals and Vanilla CSS.








δΈζη | English
---
- π 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 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.
This component is available as an Angular Library.
``bash`
npm install ng-images-preview
This library relies on Angular animations. You must enable them in your application.
Standalone (app.config.ts):
`typescript
import { provideAnimations } from '@angular/platform-browser/animations';
export const appConfig: ApplicationConfig = {
providers: [provideAnimations()]
};
`
NgModule (app.module.ts):
`typescript
import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
@NgModule({
imports: [BrowserAnimationsModule]
})
export class AppModule { }
`
Register the library in your standalone component or module.
#### Standalone (Recommended)
`typescript
import { ImagesPreviewDirective } from 'ng-images-preview';
@Component({
standalone: true,
imports: [ImagesPreviewDirective, ...]
})
export class MyComponent {}
`
#### NgModule (Legacy Support)
`typescript
import { NgImagesPreviewModule } from 'ng-images-preview';
@NgModule({
imports: [NgImagesPreviewModule, ...]
})
export class AppModule {}
`
#### A. Service-Based API (Programmatic)
Ideal for buttons, dynamic actions, or when you don't want to pollute your template with directives.
`typescript
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 ()
A ready-to-use responsive grid that handles the layout and click events for you.
`typescript
import { ImagesGalleryComponent } from 'ng-images-preview';
@Component({
imports: [ImagesGalleryComponent],
template:
[columns]="3"
gap="10px">
`
})
class MyComponent {}
#### C. Directive (The "classic" way)
Attach the preview behavior to any existing image or element.
`html

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.
`typescript
// In your component
@ViewChild('videoTpl') videoTpl: TemplateRef
openMixedGallery() {
this.service.open('img1.jpg', {
images: [
'img1.jpg',
this.videoTpl, // Use a TemplateRef here!
'img3.jpg'
]
});
}
`
`html
![]()
`
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.ImagesGalleryComponent
- No Hydration Mismatches: The internal structure remains consistent between server and client.
- Performance: The uses NgOptimizedImage for LCP-friendly image loading.
| 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. |previewSrcsets
| | string[] | [] | List of srcset strings for gallery navigation. |showNavigation
| | boolean | true | Whether to show next/prev arrow buttons. |showCounter
| | boolean | true | Whether to show the image counter (e.g. "1 / 5"). |showThumbnails
| | boolean | true | Whether to show the thumbnail strip. |showToolbar
| | boolean | true | Whether to show the top toolbar. |toolbarExtensions
| | TemplateRef | undefined | Custom template for toolbar buttons. |
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. |srcsets
| | string[] | [] | List of srcset strings for images. |showNavigation
| | boolean | true | Whether to show next/prev arrow buttons. |showCounter
| | boolean | true | Whether to show the image counter (e.g. "1 / 5"). |showThumbnails
| | boolean | true | Whether to show the thumbnail strip. |showToolbar
| | boolean | true | Whether to show the top toolbar. |toolbarExtensions
| | TemplateRef | undefined | Custom template for toolbar buttons. |
When using previewTemplate, you get access to:
#### statesrc
| Property | Type | Description |
| :--- | :--- | :--- |
| | 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. |currentIndex
| | number | Current index in gallery (0-based). |total
| | number | Total number of images in gallery. |
#### actionszoomIn()
| Method | Description |
| :--- | :--- |
| | 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). |jumpTo(index)
| | Jump to a specific index in gallery. |
You can customize the look and feel by overriding these CSS variables in your styles.css or component styles:
`css`
: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);
}
This repository is structured as an Angular Workspace.
- Library Path: projects/ng-images-previewprojects/demo
- Demo Path:
: 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.