React Lightbox: examples and API

Preview

Live preview

Changes apply to this preview only.

Width adapts to the available space

"use client";

import { Button, Lightbox, type PimoluLightboxImage } from "@pimolu/react";
import { useState } from "react";

const gallery: PimoluLightboxImage[] = [
  {
    src: "/images/pimolu-studio.webp",
    alt: "Pimolu Studio product illustration",
    caption: "Pimolu Studio — one design language for web and native.",
    thumbnail: "/images/pimolu-studio.webp",
  },
  {
    src: "/images/pimolu-avatar.svg",
    alt: "Pimolu p emblem on an indigo avatar",
    caption: "Jean Dupont · Design engineer",
    thumbnail: "/images/pimolu-avatar.svg",
  },
  {
    src: "/images/pimolu-studio.webp",
    alt: "Pimolu Studio illustration, detail view",
    caption: "Every preset shares the same component API.",
    thumbnail: "/images/pimolu-studio.webp",
  },
];

export function DemoExample() {
  const [basicOpen, setBasicOpen] = useState(false);
  return (
    <div className="grid gap-5 min-w-0">
      <Button onClick={() => setBasicOpen(true)}>Open gallery</Button>
      <span className="text-sm text-muted leading-relaxed">Three images · thumbnails · no loop</span>
      <Lightbox
        images={gallery}
        open={basicOpen}
        onOpenChange={setBasicOpen}
        showThumbnails
      />
    </div>
  );
}

More examples

Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.

A focused image viewer with a caption and explicit dismissal.

Open preview

The parent owns both the open state and the active image. Opening from a card sets the index first, so the viewer starts on the chosen image.

Open preview

Counter, thumbnail names and every control accept localized copy.

Open preview

Usage

Use useful alternative text and preserve the selected index in controlled workflows.

API reference

Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.

PimoluLightboxImage

Type source

PimoluLightboxImage public API
Name	Type	Default	Description
`src`Required	`string`	—	Full-size image URL.
`alt`Required	`string`	—	Alternative text of the image. Required on purpose.
`caption`	`ReactNode`	—	Caption rendered under the image.
`thumbnail`	`string \| undefined`	`src`	Optional thumbnail URL; defaults to `src`.

srcRequired: string
No default extracted.
Full-size image URL.
altRequired: string
No default extracted.
Alternative text of the image. Required on purpose.
caption: ReactNode
No default extracted.
Caption rendered under the image.
thumbnail: string | undefined
Default: `src`
Optional thumbnail URL; defaults to `src`.

PimoluLightboxLabels

Type source

PimoluLightboxLabels public API
Name	Type	Default	Description
`dialog`	`string \| undefined`	`"Image viewer"`	Accessible name of the modal. Defaults to "Image viewer".
`close`	`string \| undefined`	`"Close"`	Defaults to "Close".
`previous`	`string \| undefined`	`"Previous image"`	Defaults to "Previous image".
`next`	`string \| undefined`	`"Next image"`	Defaults to "Next image".
`thumbnails`	`string \| undefined`	`"Choose an image"`	Defaults to "Choose an image".
`counter`	`((position: number, total: number) => string) \| undefined`	`${position} / ${total}`	Position readout. Defaults to `${position} / ${total}`.
`goTo`	`((position: number, total: number) => string) \| undefined`	—	Accessible name of a thumbnail.

dialog: string | undefined
Default: "Image viewer"
Accessible name of the modal. Defaults to "Image viewer".
close: string | undefined
Default: "Close"
Defaults to "Close".
previous: string | undefined
Default: "Previous image"
Defaults to "Previous image".
next: string | undefined
Default: "Next image"
Defaults to "Next image".
thumbnails: string | undefined
Default: "Choose an image"
Defaults to "Choose an image".
counter: ((position: number, total: number) => string) | undefined
Default: `${position} / ${total}`
Position readout. Defaults to `${position} / ${total}`.
goTo: ((position: number, total: number) => string) | undefined
No default extracted.
Accessible name of a thumbnail.

PimoluLightboxProps

Type source

PimoluLightboxProps public API
Name	Type	Default	Description
`images`Required	`PimoluLightboxImage[]`	—	Gallery items. An empty array renders nothing.
`open`	`boolean \| undefined`	—	Controlled open state. Omit to let the component own it.
`defaultOpen`	`boolean \| undefined`	`false`	Initial open state when uncontrolled. Defaults to false.
`onOpenChange`	`((open: boolean) => void) \| undefined`	—	Called when the lightbox asks to open or close.
`index`	`number \| undefined`	—	Controlled current index. Omit to let the component own it.
`initialIndex`	`number \| undefined`	`0`	Initial index when uncontrolled. Defaults to 0.
`onIndexChange`	`((index: number) => void) \| undefined`	—	Called whenever the active image changes.
`loop`	`boolean \| undefined`	`false`	Wrap around at both ends. Defaults to false.
`closeOnOverlayClick`	`boolean \| undefined`	`true`	Close when the overlay is pressed. Defaults to true.
`closeOnEscape`	`boolean \| undefined`	`true`	Close on Escape. Defaults to true.
`showThumbnails`	`boolean \| undefined`	`false`	Render a thumbnail strip under the stage. Defaults to false.
`labels`	`PimoluLightboxLabels \| undefined`	—	Localizable labels.
`aria-label`	`string \| undefined`	—	Accessible name of the modal. Overrides `labels.dialog`.
`className`	`string \| undefined`	—	Class applied to the modal panel.

imagesRequired: PimoluLightboxImage[]
No default extracted.
Gallery items. An empty array renders nothing.
open: boolean | undefined
No default extracted.
Controlled open state. Omit to let the component own it.
defaultOpen: boolean | undefined
Default: false
Initial open state when uncontrolled. Defaults to false.
onOpenChange: ((open: boolean) => void) | undefined
No default extracted.
Called when the lightbox asks to open or close.
index: number | undefined
No default extracted.
Controlled current index. Omit to let the component own it.
initialIndex: number | undefined
Default: 0
Initial index when uncontrolled. Defaults to 0.
onIndexChange: ((index: number) => void) | undefined
No default extracted.
Called whenever the active image changes.
loop: boolean | undefined
Default: false
Wrap around at both ends. Defaults to false.
closeOnOverlayClick: boolean | undefined
Default: true
Close when the overlay is pressed. Defaults to true.
closeOnEscape: boolean | undefined
Default: true
Close on Escape. Defaults to true.
showThumbnails: boolean | undefined
Default: false
Render a thumbnail strip under the stage. Defaults to false.
labels: PimoluLightboxLabels | undefined
No default extracted.
Localizable labels.
aria-label: string | undefined
No default extracted.
Accessible name of the modal. Overrides `labels.dialog`.
className: string | undefined
No default extracted.
Class applied to the modal panel.

Accessibility

Verify Escape, previous/next controls, modal focus containment and return to the originating thumbnail.

Read the accessibility guide →

Preview

More examples

Single product image

Controlled index

Localized labels

Usage

API reference

PimoluLightboxImage

PimoluLightboxLabels

PimoluLightboxProps

Accessibility

Related components