@necraidan/ngx-lightbox

A lightweight, accessible lightbox component for Angular 21+.
Zoom, pan, pinch-to-zoom, keyboard navigation - zero external dependencies.

Features

• Standalone component, Signals API
• Double-click or scroll to zoom
• Drag to pan when zoomed
• Pinch-to-zoom on touch devices
• Keyboard navigation (Escape to close)
• i18n - fully customizable labels
• Configurable via provideNgxLightbox()
• Zero external dependencies

Installation

npm install @necraidan/ngx-lightbox

Basic usage

app.config.ts

import { provideNgxLightbox } from '@necraidan/ngx-lightbox';

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

your.component.ts

import { LightboxComponent, LightboxService, LightboxImage } from '@necraidan/ngx-lightbox';

@Component({
  imports: [LightboxComponent],
  template: `
    <button (click)="open(image)">Open</button>
    <ngx-lightbox />
  `,
})
export class YourComponent {
  private lightbox = inject(LightboxService);

  readonly image: LightboxImage = {
    src: 'https://example.com/photo.jpg',
    alt: 'A beautiful photo',
    width: 1200,
    height: 800,
  };

  open(img: LightboxImage): void {
    this.lightbox.openLightbox(img);
  }
}

i18n

import { provideNgxLightbox } from '@necraidan/ngx-lightbox';

export const appConfig: ApplicationConfig = {
  providers: [
    provideNgxLightbox(
      { showHint: true },
      {
        closeLabel: 'Fermer',
        hint: 'Double-clic pour zoomer · Molette pour ajuster · Glisser pour déplacer',
        hintMobile: 'Pincez pour zoomer · Glisser pour déplacer',
      },
    ),
  ],
};

File / Blob

Pass a File or Blob directly - the lightbox handles createObjectURL / revokeObjectURL automatically:

onFileChange(event: Event): void {
  const file = (event.target as HTMLInputElement).files?.[0];
  if (!file) return;

  const img = new Image();
  const src = URL.createObjectURL(file);
  img.onload = () => {
    this.lightbox.openLightbox({
      src: file,              // File/Blob passed directly
      alt: file.name,
      width: img.naturalWidth,
      height: img.naturalHeight,
    });
    URL.revokeObjectURL(src); // only needed for the temp img above
  };
  img.src = src;
}

Advanced

import { provideNgxLightbox, LightboxConfig, LightboxI18n } from '@necraidan/ngx-lightbox';

const config: Partial<LightboxConfig> = {
  showHint: false, // hide the zoom/pan hint
  maxScale: 8, // allow up to 8x zoom (default: 5)
  zIndex: 9999, // overlay z-index (default: 1000)
};

export const appConfig: ApplicationConfig = {
  providers: [provideNgxLightbox(config)],
};

CSS custom properties:

:root {
  --ngx-lightbox-radius: 0; /* image border-radius (default: 0.5rem) */
  --ngx-lightbox-spacing: 1.5rem; /* close button / hint spacing (default: 1rem) */
}

API Reference

LightboxConfig

Property	Type	Default	Description
showHint	boolean	true	Show the zoom/pan hint
maxScale	number	5	Maximum zoom level
zIndex	number	1000	Overlay z-index

LightboxI18n

Property	Type	Default	Description
closeLabel	string	'Close'	aria-label for the close button
hint	string	'Double-click to zoom…'	Hint text on desktop
hintMobile	string	'Pinch to zoom…'	Hint text on touch devices

LightboxService

Member	Type	Description
openLightbox(img: LightboxImage): void	void	Open the lightbox with the given image
closeLightbox()	void	Close the lightbox
lightboxImage()	Signal<LightboxImage | null>	Currently displayed image
resolvedSrc()	Signal<string | null>	Resolved URL string - use this to bind [src] when src may be a Blob
isZoomed()	Signal<boolean>	Whether the image is zoomed in
isDragging()	Signal<boolean>	Whether the user is dragging

LightboxImage

Property	Type	Description
src	string | Blob	Image source - URL string, blob URL, or a Blob/File object. The lightbox manages createObjectURL / revokeObjectURL automatically.
alt	string	Accessible description used as the alt attribute and aria-label.
width	number	Intrinsic width in pixels, used to preserve the aspect ratio before the image loads.
height	number	Intrinsic height in pixels, used to preserve the aspect ratio before the image loads.

License

MIT

Development

npm install
npx ng build ngx-lightbox
npx ng serve demo