react-image-lightbox

react-image-lightbox is a single-purpose React component that renders a fullscreen, modal image viewer on top of an existing page. Rather than managing a whole gallery, it exposes a controlled mainSrc/prevSrc/nextSrc API: the consuming app owns the image list and current index, and the component handles everything about presenting the current image well — preloading neighbors, animating transitions, and responding to mouse, touch, and pointer input.

Under the hood it wraps react-modal for the overlay and portal behavior, then layers on its own zoom, pan, and swipe logic implemented directly against pointer/touch/mouse events rather than a gesture library. Keyboard shortcuts are rate-limited so held-down arrow keys don’t skip images too fast, and image loads/errors are tracked per source type (main/prev/next) so a failed neighbor image doesn’t block the currently displayed one.

The project has not been actively developed since early 2023 — its README explicitly flags it as unmaintained and points users toward react-photoswipe-gallery as a better-supported alternative — but the published package still sees substantial weekly npm downloads, and its API surface is small and stable enough that many existing integrations continue to rely on it as-is.

What You Get

• A <Lightbox> component that renders a fullscreen modal overlay for a given mainSrc, with optional prevSrc/nextSrc for adjacent images
• Built-in pinch-to-zoom and click-to-zoom with configurable zoom buttons, plus pan support once zoomed in
• Touch swipe and mouse-drag gestures for moving between images, alongside rate-limited keyboard arrow/escape shortcuts
• Image preloading for the previous/next images so navigation feels instant instead of showing a loading flash
• Thumbnail placeholders (mainSrcThumbnail, prevSrcThumbnail, nextSrcThumbnail) shown while full-size images load, plus a customizable load-error message
• Shipped TypeScript type definitions (index.d.ts) despite the source itself being plain JavaScript

Common Use Cases

• Adding a click-to-enlarge fullscreen viewer to a photo gallery or product image grid
• Building an e-commerce product page where thumbnails expand into a zoomable, swipeable detail view
• Viewing attachments or user-uploaded images in an admin panel or CMS without leaving the page
• Portfolio and blog sites that want lightweight lightbox behavior without pulling in a jQuery-era plugin

Under The Hood

Architecture The entire component lives in a single class, ReactImageLightbox in src/react-image-lightbox.js, with supporting constants pulled from src/constant.js and small window/translation helpers from src/util.js. State (zoom level, offsets, closing/animation flags, per-source load-error status) is held directly on the component instance rather than split into hooks or child components, and static helper methods normalize mouse, touch, and pointer events into one common shape before a shared gesture-handling code path processes them. This keeps the public surface small — a single component and a props interface — at the cost of a large, monolithic implementation file that mixes rendering, gesture math, and animation timing together.

Tech Stack Built for React 16/17 as peer dependencies, with prop-types for runtime prop validation and react-modal handling the portal/overlay mechanics underneath the lightbox surface. The package is built with Rollup (CJS and ES module outputs) via Babel, styled with a plain CSS file rather than CSS-in-JS, and ships hand-written TypeScript definitions (index.d.ts) alongside its JavaScript source rather than being authored in TypeScript directly.

Code Quality Tests exist under src/__tests__ using Jest with Enzyme (mount) and snapshot testing, exercising component structure (button visibility toggles, zoom controls) rather than gesture-handling internals in depth. Enzyme’s React 16-era adapter reflects the project’s age and its lack of ongoing maintenance. ESLint is configured with the Airbnb React config, and ordinary JavaScript prop-types stand in for compile-time type safety.

API Design The component takes a deliberately minimal, controlled-input API: the app supplies mainSrc plus optional prevSrc/nextSrc and re-renders with updated props on onMovePrevRequest/onMoveNextRequest/onCloseRequest callbacks, rather than the lightbox managing an internal image list. This keeps integration straightforward for apps that already track a current index, though it does mean callers must wire up that index-tracking logic themselves rather than passing a full image array.