Lightbox

Lightbox renders an image gallery and opens the selected image in an immersive viewer. It supports responsive thumbnails, previous/next navigation, captions, titles, counters, fit modes, zoom, rotation, fullscreen, downloading, keyboard controls, localized labels, and ConfigProvider defaults.

InstallationCopy Anchor Link

import { Lightbox } from '@mosmox/ui';

Basic usageCopy Anchor Link

const images = [
  {
    id: 'lake',
    src: '/images/lake.jpg',
    thumbnailSrc: '/images/lake-thumb.jpg',
    alt: 'Mountain lake at sunrise',
    title: 'Morning light',
    caption: 'A calm lake surrounded by mountains.',
  },
  {
    id: 'valley',
    src: '/images/valley.jpg',
    alt: 'River running through a green valley',
    title: 'Valley river',
  },
];

<Lightbox items={images} aria-label="Landscape gallery" />;

The component renders a responsive trigger gallery. Clicking a thumbnail opens the viewer at that image. If thumbnailSrc is omitted, src is used for both the thumbnail and the full-size image. If no caption is supplied, the viewer uses alt as the caption when captions are enabled.

Viewer layout and controlsCopy Anchor Link

The viewer contains:

• a header with the current item title, an Image n of total counter, and a square close button;
• previous and next image buttons;
• a fit switch with Fit, Cover, and 100% modes;
• a toolbar with zoom out, zoom level, zoom in, rotate left, rotate right, fullscreen, and optional download controls;
• an optional caption below the image;
• an optional thumbnail strip/grid with the active image marked.

showToolbar controls the fit switch and the toolbar together. showThumbnails controls the thumbnails inside the viewer; showGallery controls the initial trigger gallery. A viewer can therefore be opened from a custom trigger by controlling open while setting showGallery={false}.

<Lightbox
  items={images}
  defaultIndex={1}
  loop={false}
  showGallery={false}
  showThumbnails={false}
  showCaptions={false}
  showCounter={false}
  showToolbar
  downloadable={false}
  zoom
/>

Zoom ranges from 50% to 400% in 25% increments. The actual fit mode displays the image at its natural size when possible. Rotation changes in 90° steps and resets when the selected image changes or the viewer is opened again.

Controlled opening and eventsCopy Anchor Link

Use open and onOpenChange when the parent owns the viewer state. defaultIndex determines the initial item; indexes outside the collection are clamped to a valid item.

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

<Button onClick={() => setOpen(true)}>Open gallery</Button>
<Lightbox
  items={images}
  open={open}
  defaultIndex={selectedIndex}
  onOpenChange={setOpen}
  onChange={(index, item) => {
    setSelectedIndex(index);
    analytics.track('lightbox-image-viewed', { index, id: item.id });
  }}
/>

onChange fires after navigation or thumbnail selection and receives the new zero-based index and the complete LightboxItem. onOpenChange fires when the viewer is opened or closed.

Configuration with ConfigProviderCopy Anchor Link

The nearest ConfigProvider supplies defaults for variant, fit, showCaptions, showThumbnails, and showToolbar. An instance prop always takes precedence over the provider configuration.

<ConfigProvider
  locale="uk"
  components={{
    lightbox: {
      variant: 'glass',
      fit: 'contain',
      showCaptions: true,
      showThumbnails: true,
      showToolbar: true,
    },
  }}
>
  <Lightbox items={images} />
</ConfigProvider>

The fit-mode labels are localized from the provider locale. Supported locales are en, uk, fr, and de:

Variants and fit modesCopy Anchor Link

variant="dark" is the default immersive presentation. glass adds a translucent blurred backdrop. light uses a light backdrop while keeping the image controls as dark glass overlays.

fit accepts:

• contain — show the complete image without cropping;
• cover — fill the image viewport, cropping when the aspect ratios differ;
• actual — show the image at its natural size when possible.

<Lightbox items={images} variant="light" fit="cover" />

Backdrop and keyboard behaviorCopy Anchor Link

With closeOnBackdrop enabled, clicking empty backdrop space closes the viewer. Clicking the image or a control does not. Escape also closes the viewer.

All viewer actions are native buttons with accessible labels, and the gallery receives the supplied aria-label.

API referenceCopy Anchor Link

Lightbox propsCopy Anchor Link

LightboxItemCopy Anchor Link

title and caption accept any React node, so applications can provide formatted or localized content. width and height are available as item metadata for consumers; the current viewer derives its layout from the loaded image and fit mode.