---

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

``bash
npm install ng-images-preview
`

🚀 Quick Start

$3

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 {}
`

$3

#### 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:
[images]="['img1.jpg', 'img2.jpg', 'img3.jpg']"
[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'
]
});
}
`

$3

Take full control of the preview overlay UI.

`html




`

🌏 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

$3

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

$3

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

$3

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. |
| currentIndex | number | Current index in gallery (0-based). |
| total | number | Total number of images in gallery. |

#### 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). |
| jumpTo(index) | Jump to a specific index in gallery. |

$3

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);
}
`

🛠 Development

This repository is structured as an Angular Workspace.

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

$3


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