Skip to content

Lightbox

Shows images full screen, one at a time, from a thumbnail.

lightbox-demo.tsx

Installation

The CLI adds the files, packages, theme variables, and Tailwind plugin that this component uses. Before you run it, set up your project.

Usage

trip-photos.tsx

Composition

  • Lightbox

    Owns the open state and the index. Returns focus to the trigger of the current image.

    • LightboxTriggerRepeats

      Needs aria-label. Its image is the zoom origin.

    • LightboxContent
      • Carousel

        Install separately.

        • CarouselSlideRepeats
          • LightboxImage
      • LightboxCountOptional
      • LightboxClose

Captions

lightbox-captions-demo.tsx

Controlled index

Bind index to keep a page gallery and the lightbox in step.

0 / 0

lightbox-controlled-demo.tsx

Single image

lightbox-single-demo.tsx

API reference

vip/ui adds or changes the props below. For all other props, see React Aria Modal (opens in a new tab).

Lightbox

Owns the open state and the index. Returns focus to the trigger of the current image.

isOpen: boolean
Controls the open state.
defaultOpen: boolean = false
Opens the viewer at first.
onOpenChange: (isOpen: boolean) => void
Receives requests to open or close the viewer.
index: number
Sets the current image. A change moves the carousel to that image.
defaultIndex: number = 0
Sets the image that opens first when no thumbnail is pressed.
onIndexChange: (index: number) => void
Receives the image that becomes current from an arrow key, a side button, or a swipe.

LightboxTrigger

Renders a thumbnail button. Its image is the zoom origin and the focus target after close.

index: numberRequired
Sets the image that a press opens.
aria-label: stringRequired
Names the thumbnail. The image inside it is decorative.
className: string
Styles the thumbnail frame.

LightboxContent

Renders the modal, the image carousel, the count, the side buttons, and the close button. Its children are the slides.

aria-label: string = "Image viewer"
Names the dialog.
className: string
Styles the dialog surface.

LightboxImage

One slide. Pass children instead of src for a custom graphic.

src: string
The image URL.
alt: stringRequired
Describes the image for screen readers.
width: number
The image width in pixels. The image never upscales past it.
height: number
The image height in pixels.
caption: string
Shows text under the image.

LightboxCount

Shows the current image, such as 2 of 5. Renders nothing for a single image.

LightboxClose

Renders an icon-only ghost Button named Close. It takes Button props.