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:

URL State

LightboxUrlOverlay is a separate component whose open state lives in the address bar. Build a controller with useOverlayUrlState from @reelkit/react 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.

The hook takes one options object and returns a UrlStateController (with set, index, value). Keep it for programmatic control: set is the low-level write the overlay uses internally (slide change, and set(null) to close). It drives the overlay programmatically too — set(index) opens it, the same as navigating to the parameter. Prefer a link for opening though: the href is shareable, opens in a new tab, and the back button closes it — all for free, with no handler.

Full useOverlayUrlState options (param, adapter, codec, locator): see the React API reference.

LightboxUrlOverlay itself takes just controller (required), an optional onClose, plus every visual and behavior prop LightboxOverlay takes (images, ariaLabel, transitionFn, the render props, and so on) — but no isOpen.

• Opening costs one history entry. Paging slides replaces it, so a hundred swipes add none — one back step always leaves the gallery. Back closes; it does not step through photos.
• A shared link like ?photo=3 opens the gallery at that slide. Closing a link that arrived with the page removes the parameter in place rather than navigating off your site.
• Back closes only when you opened from within the app — the link pushed an entry, so back pops to the gallery. A shared link opened directly in a fresh tab has no history behind it, so browser-back leaves the site; the close button or Escape removes the parameter in place and keeps you on the gallery.
• A parameter naming no slide — a stale bookmark, a hand-edited value — is dropped from the URL instead of leaving the address bar asserting a slide that cannot open.

In a routed app, pass an adapter. Writing history directly leaves the router's own location stale, and its next navigation drops the parameter.

Opening is a link. Because the open state lives in the URL, a thumbnail is an ordinary link — no click handler — and the browser's own behaviour comes free: open in a new tab, copy the address, preview on hover. In a routed app use the router's link so it stays client-side.

Prefer a stable identity for shareable links. The index is positional, so 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/locator yourself:

Infinite or paginated galleries. The sync locate can only answer 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.

• How you load is up to you — fetch contiguous pages up to the target, or fetch just that one image and append it. The URL keys by identity, not position, so findIndex returns wherever the item lands.
• While locateAsync is pending the lightbox stays closed and the parameter is left alone, so the deep link survives the fetch. null or a rejection drops the parameter.
• An answer arriving after the URL moved on, after a close, or after unmount is discarded — a slow fetch cannot open a slide nobody asked for.
• Nothing is rendered while pending; the page already owns that loading state, so render your own skeleton.
• There is no timeout — the lightbox cannot know how long the gallery is. Settle with null when pagination is exhausted, or the overlay stays closed indefinitely.
• Whatever locateAsync returns is authoritative — the index of data it just fetched, taken as-is without re-reading images.

API Reference

LightboxOverlay Props

LightboxOverlayProps

LightboxUrlOverlay Props

LightboxUrlOverlayProps

Takes every visual and behaviour prop above except isOpen, and replaces it with a controller. initialIndex is ignored here — the controller's position picks the slide, so a value passed alongside it would be overwritten on every open.

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.