Lightbox

Features

Installation

Don't forget to import the styles:

Quick Start

The LightboxOverlay component displays images in fullscreen. Pass an array of LightboxItem objects and control visibility with a nullable index.

Live Demo

PreviewCode

LightboxPage.tsxStackBlitz

Mountain River

Snowy Peaks

Foggy Forest

Ocean Waves

Autumn Path

Coastal Cliffs

Click a thumbnail to open the lightbox. Use arrow keys or swipe to navigate.

Video Slides (Opt-in)

Video support is fully opt-in and tree-shakeable — image-only usage pays zero extra bundle cost. Import useVideoSlideRenderer and wire its return values into LightboxOverlay. The hook handles loading states, sound management, and video lifecycle automatically.

Customization

Custom Controls

Use renderControls to replace the default close button, counter, and fullscreen toggle. Compose with the exported sub-components:

Custom Info Overlay

Use renderInfo to replace the default title/description gradient, or pass renderInfo={() => null} to hide it entirely:

Custom Navigation

Use renderNavigation to replace the default prev/next arrows:

Custom Slide

Use renderSlide for fully custom slide content. Return null to fall back to the default image slide:

Content Loading & Error Handling

The lightbox tracks per-slide loading and error states. A spinner shows while content loads; a broken-image icon shows for failed media. Errored URLs are cached so revisiting shows the error instantly without retrying.

Lifecycle Callbacks

When using renderSlide, call these callbacks to control the loading indicator:

Custom Loading & Error UI

Replace the default spinner and error icon with custom components:

API Reference

Props

Callbacks

Reel Props (proxied)

These props are forwarded to the underlying Reel component.

Types

LightboxItem

ControlsRenderProps

NavigationRenderProps

SlideRenderProps

InfoRenderProps

Sub-Components

Reusable sub-components for composing custom controls via renderControls.

CloseButton

Default X close button.

Counter

Image counter pill showing "1 / 3".

FullscreenButton

Fullscreen toggle button (Maximize/Minimize icon).

SoundButton

Mute/unmute toggle button for video slides (Volume2/VolumeX icon). Included automatically in renderControls from useVideoSlideRenderer. For standalone use inside custom controls, access sound state via useSoundState.

Hooks

useVideoSlideRenderer

Hook for opt-in video support. Returns renderSlide, renderControls, and SoundProvider — wrap the overlay in SoundProvider and pass the render functions.

useFullscreen

Hook for managing fullscreen state with cross-browser support.

Transitions

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

Custom Transition Function

Author your own TransitionTransformFn and pass it via transitionFn. The signature mirrors core slider transitions.

CSS Classes

All UI elements use plain CSS classes (not CSS modules) that can be targeted with higher-specificity selectors in a stylesheet loaded after @reelkit/react-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.

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

Accessibility

The overlay root is a modal dialog (role="dialog", aria-modal="true"). Set ariaLabel to change the screen-reader announcement; it defaults to "Image gallery". Each slide carries role="group", aria-roledescription="slide", and aria-label="Image N of M".

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.