Lightbox
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.
Installation
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
Requires React 19+, base CSS and a Theme provider. See Setup.
Lightbox
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| isOpen * | boolean | Whether the lightbox is open. | |
| onOpenChange * | (isOpen: boolean) => void | Callback when the lightbox open state changes. | |
| media * | LightboxMedia | LightboxMedia[] | 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 | false | Enable zoom on double-click, or Enter/Space/+/- via keyboard (images only). When zoomed, drag or use arrow keys to pan. |
| defaultIndex | number | 0 | Initial image index in gallery mode for uncontrolled usage. |
| hasAutoPlay | boolean | false | Automatically start video playback when a video media item is shown. |
| xstyle | StyleXStyles | StyleX styles for layout customization. Must be stylex.create() value. |
Usage guidance
- 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.
- Avoid: Use the lightbox for non-image content; it is specialized for images.
- Avoid: Nest interactive content inside captions; keep them plain text.
Theming API
{
"targets": [
{
"className": "astryx-lightbox",
"visualProps": []
}
]
}
Anatomy
- Viewer overlay: Full-viewport dialog overlay that contains the active media and controls.
- Media: Active image or video presented inside the viewer.
- Close button: Button that closes the viewer.
- Previous button: Gallery button that moves to the previous media item.
- Next button: Gallery button that moves to the next media item.
- Caption: Caller-provided caption displayed below the active media.
- Counter: Current position and total shown in gallery mode.
Examples
- Lightbox: A fullscreen image viewer with caption.
- Lightbox — Gallery: A thumbnail grid that opens a fullscreen gallery. Clicking any thumbnail opens the lightbox at that index. Prev/next navigation lets users browse all images without closing.
- Lightbox — Video: Opens a video in the lightbox. Native browser controls are available. Zoom and pan are disabled for video items.
- Lightbox — Zoom: A lightbox with zoom and pan enabled. Double-click the image to zoom in; drag to pan around. Double-click again or use the close button to exit.