Live Docs

Navigation

Effects & Media /

new

Lightbox

Full-screen image viewer in a portal: pinch / wheel / pan zoom, swipe + keyboard navigation, thumbnails, and scroll-lock.

import { Lightbox } from "@naraya-ai/ui";

Examples

Controlled

Drive open/index yourself. Scroll/pinch to zoom, drag to pan, arrows/swipe to navigate, Esc to close.

const [open, setOpen] = useState(false);

<Button onClick={() => setOpen(true)}>Open lightbox</Button>
<Lightbox open={open} onOpenChange={setOpen} items={items} thumbnails />

Gallery + Trigger (hover overlay)

Wrap thumbnails in a gallery; each trigger opens at its index — no state wiring. Small thumbs use an icon-only overlay; larger ones add a label.

<Lightbox.Gallery items={items}>
  {/* small thumb — icon only */}
  <Lightbox.Trigger index={i} overlay>
    <img src={it.thumb} alt={it.alt} />
  </Lightbox.Trigger>

  {/* larger thumb — icon + label */}
  <Lightbox.Trigger index={0} overlay overlayLabel="Preview">
    <img src={cover} alt="…" />
  </Lightbox.Trigger>
</Lightbox.Gallery>

Props (core)

PropTypeDefaultDescription
open*boolean—Visibility of the viewer.
onOpenChange*(open: boolean) => void—Open/close callback.
items*LightboxItem[]—{ src, alt?, caption?, thumb? }[].
index / defaultIndexnumber0Controlled / uncontrolled active item.
onIndexChange(index: number) => void—Active-item callback.
loopbooleantrueWrap prev/next navigation.
thumbnailsbooleanfalseShow the thumbnail strip.
zoom"pinch" | "click" | false"pinch"Zoom interaction model.
closeOnBackdropbooleantrueClick backdrop to close.
renderItem(item, index) => ReactNode—Custom item renderer (e.g. video).

Gallery & Trigger

PropTypeDefaultDescription
Lightbox.Galleryelement—Manages open/index; takes the same props as the core minus open/index.
Lightbox.Triggerelement—Opens the gallery at `index` when clicked.
Trigger.overlaybooleanfalseFrosted expand affordance on hover/focus.
Trigger.overlayLabelReactNode—Label beside the icon (use for larger thumbnails).
Trigger.overlayIconReactNode—Override the overlay icon (default: expand glyph).

Keyboard & gestures

  • ← / → navigate, Esc closes, + / − zoom, 0 resets zoom.
  • Pinch (touch) and mouse-wheel zoom toward the pointer; double-click toggles zoom.
  • Drag to pan while zoomed; swipe to navigate when not zoomed.
  • Stacked lightboxes: only the topmost responds to keys, so Esc closes it first.

Accessibility

  • role='dialog' aria-modal='true'; body scroll is locked while open.
  • Focus moves into the dialog on open and returns to the trigger on close; Tab is trapped.
  • Always provide meaningful alt text on items.