Angular Lightbox

Features

Installation

Basic Usage

Import the styles and the RkLightboxOverlayComponent standalone component into your component's imports array.

Template Slots

Four template slot directives allow full customization of the overlay UI without forking the component. Each slot receives a strongly-typed context object.

Video Support

Video slides require opting in via the rkLightboxSlide template slot and the RkLightboxVideoSlideComponent. This design avoids bundling the video player for galleries that only need images.

Fullscreen

Use fullscreenSignal, requestFullscreen, and exitFullscreen from @reelkit/angular to observe or toggle fullscreen state.

URL State

RkLightboxUrlOverlayComponent is a separate component whose open state lives in the address bar. Build a controller with createOverlayUrlState and hand it over as [controller]: the gallery opens itself when the parameter names a slide and closes when it goes away. Links are shareable, and the back button closes the gallery instead of leaving the page.

Call it in an injection context — a field initialiser or the constructor. It attaches immediately and releases through DestroyRef, so a component destroyed while the gallery is open leaves no listener behind. Full options live in the Angular API reference.

• Opening pushes one history entry. Paging slides replaces it, so N steps add no entries and one back step always leaves the gallery.
• Back closes only when the gallery was opened from within the app — the link pushed an entry. A shared link opened directly in a fresh tab has no history behind it, so browser-back leaves the site; the ✕ button or Escape removes the parameter in place and stays.
• A parameter naming no slide — a stale bookmark, a hand-edited value — is dropped from the URL rather than left asserting a slide that cannot open.
• Template slots work unchanged: the url component runs the six slot queries itself and forwards each template to the gallery, so rkLightboxControls and its siblings sit inside it exactly as they would inside rk-lightbox-overlay.
• In a routed application pass an adapter built on Router. Writing history behind the Router leaves its location stale and its next navigation drops the parameter.

In a routed app, pass an adapter. Writing history behind the Router leaves its location stale and its next navigation drops the parameter, so build an adapter on Router and pass it as adapter:

Stable links. The index is positional — a bookmarked ?photo=3 opens a different image once the list is reordered. urlStableIdKey keys by each item's stable id, scanning the live list — one call covers the common case.

Pass hashCodec: base64UrlCodec to base64url-encode the id in the URL — reversible obfuscation, not a cryptographic hash.

Key by a different field (a slug), or page an infinite feed with locateAsync, and build the codec (wire) and locator (lookup) yourself:

Infinite or paginated galleries. locate is synchronous, so it only answers for images already loaded — a shared link to image 400 of a feed that has loaded 20 comes up empty. locateAsync is the fallback, called only when locate misses: load the pages you need, then return the index the identity turned out to have. While it is pending the gallery stays closed and the parameter is left alone, so the deep link survives the fetch; null or a rejection drops the parameter.

RkLightboxUrlOverlayComponent Inputs

Takes every input of rk-lightbox-overlay except isOpen, replaced by a controller. Outputs are the same closed and slideChange; the URL drives closing, so closed is a notification rather than the mechanism.

RkLightboxOverlayComponent Inputs

RkLightboxOverlayComponent Outputs

LightboxItem Interface

Template Slot Context Types

Transitions

Pass any TransitionTransformFn via the transitionFn input. Importing only the transition you use lets the bundler tree-shake the rest. Defaults to slideTransition when omitted.

Content Loading & Error Handling

When using the rkLightboxSlide template slot, three lifecycle callbacks are available on the context to report loading state. The lightbox tracks per-slide state and shows a spinner or error icon accordingly. A content preloader caches broken URLs so revisiting a failed slide skips the retry.

Lifecycle Callbacks

Wiring Callbacks in rkLightboxSlide

Custom Loading Template

Use the rkLightboxLoading directive to replace the default spinner.

Custom Error Template

Use the rkLightboxError directive to replace the default error icon.

CSS Classes

All CSS classes are plain (not scoped), so they can be targeted with higher-specificity selectors in a stylesheet loaded after @reelkit/angular-lightbox/styles.css. For color, size, and z-index changes, prefer the CSS custom properties documented in the Theming section below.

Theming

Every color, size, z-index, and transition lives in a CSS custom property. Override one or many at :root (or any ancestor of the lightbox) to retheme without touching component source. The tokens match the React lightbox, so overrides port between bindings.

Drop the snippet below into a stylesheet loaded after @reelkit/angular-lightbox/styles.css.

Accessibility

The overlay root is a modal dialog (role="dialog", aria-modal="true"). Set the ariaLabel input to change the screen-reader announcement; it defaults to "Image gallery". Each slide carries role="group", aria-roledescription="slide", and an aria-label derived from the image title plus position.

The lightbox captures focus on open and returns it to the trigger on close. Tab and Shift+Tab cycle through focusable elements inside; focus that escapes (click outside, programmatic focus) gets pulled back. Implemented with captureFocusForReturn and createFocusTrap from @reelkit/core.