@reelkit/angular-lightbox

@reelkit/angular-lightbox

Image gallery lightbox for Angular — opens full-screen with swipe navigation, keyboard controls, and transition effects. Every part of the UI is replaceable via template slots. ~12.5 kB gzip.

Live Demo

Installation

npm install @reelkit/angular-lightbox @reelkit/angular lucide-angular

Quick Start

import { Component, signal } from '@angular/core';
import {
  RkLightboxOverlayComponent,
  type LightboxItem,
} from '@reelkit/angular-lightbox';

@Component({
  standalone: true,
  imports: [RkLightboxOverlayComponent],
  template: `
    @for (img of images; track img.src; let i = $index) {
      <img [src]="img.src" (click)="open(i)" />
    }
    <rk-lightbox-overlay
      [isOpen]="isOpen()"
      [items]="images"
      [initialIndex]="startIndex()"
      (closed)="isOpen.set(false)"
    />
  `,
})
export class GalleryComponent {
  isOpen = signal(false);
  startIndex = signal(0);

  images: LightboxItem[] = [
    {
      src: 'https://example.com/image1.jpg',
      title: 'Sunset',
      description: 'Beautiful sunset over the ocean',
    },
    { src: 'https://example.com/image2.jpg', title: 'Mountains' },
  ];

  open(index: number) {
    this.startIndex.set(index);
    this.isOpen.set(true);
  }
}

Features

• Touch gestures — swipe to navigate, swipe up to close
• Keyboard navigation — arrow keys, Escape
• Fullscreen — cross-browser Fullscreen API
• Transitions — slide, fade, and zoom-in effects
• Image preloading — adjacent images prefetched
• Video slides (opt-in) — via rkLightboxSlide template slot
• Counter — "1 / 10" indicator
• Info overlay — title and description with gradient
• Template slots — rkLightboxControls, rkLightboxNavigation, rkLightboxInfo, rkLightboxSlide to override any part
• Sub-components — RkCloseButtonComponent, RkCounterComponent, RkFullscreenButtonComponent, RkSoundButtonComponent

Template Slots

Directive	Description
rkLightboxControls	Custom controls (close, counter, etc.)
rkLightboxNavigation	Custom prev/next navigation arrows
rkLightboxInfo	Custom title/description overlay
rkLightboxSlide	Custom slide renderer (required for video slides)

API Reference

rk-lightbox-overlay Inputs

Input	Type	Default	Description
isOpen	boolean	required	Controls lightbox visibility
items	LightboxItem[]	required	Array of items to display
initialIndex	number	0	Starting image index
transition	TransitionType	'slide'	Transition animation type
showInfo	boolean	true	Show title/description
loop	boolean	false	Enable infinite loop
enableNavKeys	boolean	true	Enable keyboard navigation
enableWheel	boolean	true	Enable mouse wheel
wheelDebounceMs	number	200	Wheel debounce (ms)
transitionDuration	number	300	Animation duration (ms)
swipeDistanceFactor	number	0.12	Swipe threshold (0-1)

rk-lightbox-overlay Outputs

Output	Type	Description
closed	void	Emitted when lightbox closes
slideChange	number	Emitted after slide change

Types

interface LightboxItem {
  src: string;
  type?: 'image' | 'video';
  poster?: string;
  title?: string;
  description?: string;
  width?: number;
  height?: number;
}

type TransitionType = 'slide' | 'fade' | 'zoom-in';

Sub-components

Use these inside custom rkLightboxControls templates:

Component	Description
RkCloseButtonComponent	Close button
RkCounterComponent	"1 / 10" counter
RkFullscreenButtonComponent	Fullscreen toggle
RkSoundButtonComponent	Mute/unmute toggle

Keyboard Shortcuts

Key	Action
ArrowLeft	Previous image
ArrowRight	Next image
Escape	Close lightbox (or exit fullscreen)

CSS Classes

All UI elements use CSS classes prefixed with rk-lightbox-:

Class	Description
.rk-lightbox-overlay	Root container
.rk-lightbox-close	Close button
.rk-lightbox-nav	Navigation arrows
.rk-lightbox-nav-prev	Previous arrow
.rk-lightbox-nav-next	Next arrow
.rk-lightbox-counter	Image counter
.rk-lightbox-btn	Control buttons
.rk-lightbox-info	Title/description container
.rk-lightbox-title	Image title
.rk-lightbox-description	Image description
.rk-lightbox-slide	Slide container
.rk-lightbox-img	Image element
.rk-lightbox-video-container	Video slide wrapper
.rk-lightbox-video-element	Video element
.rk-lightbox-video-poster	Video poster image
.rk-lightbox-video-error	Video error state container
.rk-lightbox-top-shade	Top gradient scrim
.rk-lightbox-spinner	Default loading spinner
.rk-lightbox-img-error	Image error state container
.rk-lightbox-swipe-hint	Mobile swipe hint chip
.rk-lightbox-empty	Empty state text

Theming via CSS custom properties

Every visual value is exposed as a --rk-lightbox-* custom property with a sensible default. Override at :root (or any ancestor of .rk-lightbox-overlay) to retheme without touching component source — see the Theming docs for the full token table.

Documentation

Docs, demos, and customization examples at reelkit.dev/docs/angular-lightbox.

Support

If ReelKit saved you some time, a star on GitHub would mean a lot — it's a small thing, but it really helps the project get noticed.

License

MIT