Lightbox

Pro

Photo gallery where any tapped photo grows out of its exact tile into a full-screen viewer, then flies back into the tile of whichever photo is showing when you let it go.

Preview

Installation

npx @lumioui/cli add pro/lightbox

Usage

import { LightboxProvider, useLightbox, LightboxImage } from "@/components/ui/lightbox/lightbox";
<Lightbox />

Also exported: LightboxProvider, useLightbox, LightboxImage.

Examples

Photo feed

A shared trip album in a 3-column square grid with hairline gutters.

Listing gallery

The rental-listing photo mosaic at the top of a stay: one hero and a 2×2 grid, the last tile carrying "+N".

API reference

LightboxProvider

Prop Type Default
children* React.ReactNode —
onOpen (gallery: string, index: number) => void

Fires when the viewer opens a photo (gallery, index).

—
filmstrip boolean

Thumbnail filmstrip along the bottom of the viewer for galleries of 3+ photos — it scrubs with the swipe; tap a thumb to jump. Default true.

true

LightboxImage

Prop Type Default
source* ImageSourcePropType —
fullSource ImageSourcePropType

Larger source for the full-screen viewer. Default: source.

—
gallery string

Photos sharing a gallery page together in the viewer. Default: its own.

—
index number

Order within the gallery. Default 0.

0
radius number

Tile corner radius in pt — the zoom rounds out of it. Default 16.

16
aspectRatio number

Photo aspect (w / h) for a pixel-perfect morph when the tile crops it.

—
caption string

Caption shown under the photo in the viewer (swaps in place as you page).

—
className string

Size / layout classes for the tile (e.g. "h-48 w-full").

—
style StyleProp<ViewStyle> —
accessibilityLabel string

Screen-reader label, e.g. "Living room, photo 2 of 8". Also describes the photo in the viewer when there is no caption.

—
children React.ReactNode

Overlay content drawn on top of the photo (badges, captions).

—
onPress () => void

Called on tap, alongside opening the viewer.

—
onLongPress () => void

Long-press handler (e.g. open a Save / Share / Hide menu). A long-press never opens the viewer. Fires a medium haptic.

—
lit boolean

Hero tile: in dark scheme it carries a 1px lit top edge (LitEdge). Use on the one lead photo of a screen, not every grid square. Default false.

false