'/%3e%3c!--%20Motion%20trails%20--%3e%3crect%20x='14'%20y='7'%20width='12'%20height='2'%20rx='1'%20fill='white'%20opacity='.2'/%3e%3crect%20x='12'%20y='12'%20width='16'%20height='2'%20rx='1'%20fill='white'%20opacity='.35'/%3e%3crect%20x='10'%20y='17'%20width='20'%20height='2.5'%20rx='1.25'%20fill='white'%20opacity='.5'/%3e%3c!--%20Bold%20chevron%20down%20--%3e%3cpath%20d='M10%2024%20L20%2034%20L30%2024'%20stroke='white'%20stroke-width='3.5'%20stroke-linecap='round'%20stroke-linejoin='round'%20fill='none'/%3e%3c/svg%3e)
Angular Lightbox
Full-screen image & video gallery lightbox for Angular, built on @reelkit/angular-lightbox.
Features
Installation
Icons
lucide-angular for icons. If you prefer a different icon library, use the rkLightboxControls and rkLightboxNavigation template slots to provide your own.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.
| Directive | Context Type | Description |
|---|---|---|
| [rkLightboxControls] | LightboxControlsContext | Replace the top controls bar (close button, counter, fullscreen toggle) |
| [rkLightboxNavigation] | LightboxNavContext | Replace the prev/next navigation arrows |
| [rkLightboxInfo] | LightboxInfoContext | Replace the bottom title/description gradient overlay |
| [rkLightboxSlide] | LightboxSlideContext | Replace individual slide content (required for video slides) |
| [rkLightboxLoading] | { $implicit: activeIndex, item } | Custom loading indicator |
| [rkLightboxError] | { $implicit: activeIndex, item } | Custom error indicator |
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.
RkLightboxOverlayComponent Inputs
| Input | Type | Default | Description |
|---|---|---|---|
| isOpen | boolean | required | Controls visibility; when false the overlay is removed from the DOM |
| items | LightboxItem[] | required | Array of lightbox items (images or videos) |
| initialIndex | number | 0 | Zero-based index of the initially visible item |
| transitionFn | TransitionTransformFn | slideTransition | Slide transition function. Import a built-in (slideTransition, flipTransition, lightboxFadeTransition, lightboxZoomTransition) or pass a custom one. Defaults to slideTransition when omitted. |
| showInfo | boolean | true | Whether to render the title/description info overlay |
| showControls | boolean | true | Whether to render the top controls bar (close, counter, fullscreen) |
| showNavigation | boolean | true | Whether to render the prev/next navigation arrows |
| transitionDuration | number | 300 | Slide animation duration in ms |
| swipeDistanceFactor | number | 0.12 | Minimum swipe distance fraction (0–1) to trigger slide change |
| swipeToCloseDirection | 'up' | 'down' | 'up' | Direction of the swipe-to-close gesture on mobile |
| loop | boolean | false | Whether the slider wraps from the last slide back to first |
| enableNavKeys | boolean | true | Enable keyboard arrow key navigation |
| enableWheel | boolean | true | Enable mouse wheel navigation |
| wheelDebounceMs | number | 200 | Debounce duration for wheel events in ms |
| ariaLabel | string | 'Image gallery' | Accessible label for the dialog region |
RkLightboxOverlayComponent Outputs
| Output | Type | Description |
|---|---|---|
| closed | EventEmitter<void> | Emitted when the user closes the lightbox |
| slideChange | EventEmitter<number> | Emitted when the active slide index changes |
LightboxItem Interface
| Field | Type | Required | Description |
|---|---|---|---|
| src | string | yes | URL of the image or video |
| type | 'image' | 'video' | no | Item type. Defaults to 'image' |
| poster | string | no | Thumbnail image for video items |
| title | string | no | Title shown in the info overlay |
| description | string | no | Description shown below the title |
| width | number | no | Intrinsic image width in pixels |
| height | number | no | Intrinsic image height in pixels |
Template Slot Context Types
| Type | Fields |
|---|---|
| LightboxControlsContext | { item, onClose, activeIndex, count, isFullscreen, onToggleFullscreen } |
| LightboxNavContext | { item, onPrev, onNext, activeIndex, count } |
| LightboxInfoContext | { $implicit: LightboxItem, index } |
| LightboxSlideContext | { $implicit: LightboxItem, index, size: [number, number], isActive, onReady, onWaiting, onError } |
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.
| Function | From | Description |
|---|---|---|
| slideTransition | @reelkit/angular-lightbox | Standard horizontal slide (default) |
| lightboxFadeTransition | @reelkit/angular-lightbox | Crossfade between images |
| flipTransition | @reelkit/angular-lightbox | 3D card flip effect |
| lightboxZoomTransition | @reelkit/angular-lightbox | Zoom in from smaller to normal size |
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
| Callback | Type | Description |
|---|---|---|
| onReady | () => void | Notify that the slide content has loaded successfully (e.g. image decoded) |
| onWaiting | () => void | Notify that the slide content is loading/buffering (shows spinner) |
| onError | () => void | Notify that the slide content failed to load (shows error icon) |
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.
| Class | Component | Description |
|---|---|---|
| .rk-lightbox-overlay | Overlay | Root container (full-screen backdrop) |
| .rk-lightbox-top-shade | Overlay | Top gradient scrim behind controls |
| .rk-lightbox-spinner | Overlay | Default loading spinner |
| .rk-lightbox-img-error | Overlay | Error state container (broken image) |
| .rk-lightbox-img-error-text | Overlay | Error state text label |
| .rk-lightbox-swipe-hint | Overlay | Mobile swipe hint |
| .rk-lightbox-empty | Overlay | Empty state text |
| .rk-lightbox-controls-left | Controls | Top-left controls container |
| .rk-lightbox-btn | Controls | Control button (fullscreen, etc.) |
| .rk-lightbox-close | Controls | Close button |
| .rk-lightbox-counter | Controls | Image counter chip |
| .rk-lightbox-nav | Navigation | Navigation arrow (both prev and next) |
| .rk-lightbox-nav-prev | Navigation | Previous arrow |
| .rk-lightbox-nav-next | Navigation | Next arrow |
| .rk-lightbox-info | Info | Title / description container |
| .rk-lightbox-title | Info | Image title |
| .rk-lightbox-description | Info | Image description |
| .rk-lightbox-slide | Slide | Slide container |
| .rk-lightbox-img | Slide | Image element |
| .rk-lightbox-video-container | VideoSlide | Video slide container (opt-in) |
| .rk-lightbox-video-element | VideoSlide | Video element (opt-in) |
| .rk-lightbox-video-poster | VideoSlide | Video poster image (opt-in) |
| .rk-lightbox-video-error | VideoSlide | Video error state container |
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.
| Token | Default | Controls |
|---|---|---|
| --rk-lightbox-overlay-bg | #000 | Full-screen backdrop color |
| --rk-lightbox-overlay-z | 9999 | Overlay z-index |
| --rk-lightbox-top-shade-height | 80px | Top gradient scrim height |
| --rk-lightbox-top-shade-bg | linear-gradient(rgba(0,0,0,0.6), transparent) | Top gradient scrim color |
| --rk-lightbox-edge-padding | 16px | Edge inset for close / nav / top-left controls |
| --rk-lightbox-controls-gap | 12px | Gap between top-left controls |
| --rk-lightbox-transition | 0.2s | Button hover transition duration |
| --rk-lightbox-blur | 8px | Backdrop blur radius for buttons / chips |
| --rk-lightbox-btn-bg | rgba(0, 0, 0, 0.5) | Default background for close, nav, small buttons |
| --rk-lightbox-btn-bg-hover | rgba(255, 255, 255, 0.2) | Hover background for close, nav, small buttons |
| --rk-lightbox-btn-fg | #fff | Icon color for close, nav, small buttons |
| --rk-lightbox-btn-size | 36px | Small button size (fullscreen toggle, etc.) |
| --rk-lightbox-close-size | 40px | Close button size |
| --rk-lightbox-nav-size | 48px | Prev/next arrow size |
| --rk-lightbox-nav-opacity | 0.7 | Idle opacity of prev/next arrows |
| --rk-lightbox-counter-fg | #fff | Counter text color |
| --rk-lightbox-counter-bg | rgba(0, 0, 0, 0.5) | Counter chip background |
| --rk-lightbox-counter-size | 14px | Counter font size |
| --rk-lightbox-counter-padding | 6px 12px | Counter chip padding |
| --rk-lightbox-counter-radius | 20px | Counter chip border-radius |
| --rk-lightbox-spinner-size | 28px | Default spinner width/height |
| --rk-lightbox-spinner-duration | 0.8s | Spinner rotation duration |
| --rk-lightbox-error-fg | rgba(255, 255, 255, 0.4) | Error icon + text color |
| --rk-lightbox-info-bg | linear-gradient(transparent, rgba(0,0,0,0.8)) | Caption scrim gradient |
| --rk-lightbox-info-padding | 24px | Caption inner padding |
| --rk-lightbox-title-size | 18px | Title font size |
| --rk-lightbox-description-size | 14px | Description font size |
| --rk-lightbox-hint-fg | rgba(255, 255, 255, 0.5) | Swipe hint text color |
| --rk-lightbox-hint-bg | rgba(0, 0, 0, 0.3) | Swipe hint chip background |
| --rk-lightbox-video-bg | #000 | Letterbox background behind <video> |
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.
Keyboard Shortcuts
| Key | Action |
|---|---|
| ArrowLeft | Previous image |
| ArrowRight | Next image |
| Escape | Close lightbox (or exit fullscreen if active) |