A fullscreen overlay for viewing images and videos at full resolution. Supports single-item and gallery modes with prev/next navigation, optional zoom and pan for images, and native video controls.
Preview loads on approachPreview loads on approach
Exact source · lightbox-showcase
// Copyright (c) Meta Platforms, Inc. and affiliates.
import {useState} from 'react';
import {Lightbox} from '@astryxdesign/core/Lightbox';
export default function LightboxShowcase() {
const [isOpen, setIsOpen] = useState(false);
return (
<>
<button onClick={() => setIsOpen(true)}>View image</button>
<Lightbox
isOpen={isOpen}
onOpenChange={setIsOpen}
media={{
src: '/template-assets/light-scene-horizontal-1.png',
alt: 'Coastal shoreline with ocean waves',
caption:
'A scenic coastline with waves rolling onto a sandy beach beneath a clear sky.',
}}
/>
</>
);
}
Usage
A fullscreen overlay for viewing images and videos at full resolution. Supports single-item and gallery modes with prev/next navigation, optional zoom and pan for images, and native video controls.
Always provide alt text for every image for screen reader accessibility.
Use gallery mode with onIndexChange for multi-image sets.
Enable hasZoom only when viewing high-resolution images that benefit from close inspection.
Use the lightbox for non-image content; it is specialized for images.
Nest interactive content inside captions; keep them plain text.
Typed props
Prop
Type and behavior
isOpen
boolean · required
Whether the lightbox is open.
onOpenChange
(isOpen: boolean) => void · required
Callback when the lightbox open state changes.
media
LightboxMedia | LightboxMedia[] · required
Media to display. Pass a single object for one item, or an array for gallery mode with prev/next navigation. Each item is {src: string, alt: string, caption?: ReactNode, type?: 'image' | 'video'}; type defaults to 'image', and zoom/pan is disabled for 'video'.
index
number
Current index in gallery mode (when media is an array).
onIndexChange
(index: number) => void
Callback when the gallery index changes via prev/next navigation.
hasZoom
boolean · default false
Enable zoom on double-click, or Enter/Space/+/- via keyboard (images only). When zoomed, drag or use arrow keys to pan.
defaultIndex
number · default 0
Initial image index in gallery mode for uncontrolled usage.
hasAutoPlay
boolean · default false
Automatically start video playback when a video media item is shown.
xstyle
StyleXStyles
StyleX styles for layout customization. Must be stylex.create() value.
Anatomy
Viewer overlay · required
Full-viewport dialog overlay that contains the active media and controls.
Media · required
Active image or video presented inside the viewer.
