# Lightbox

- Page: https://jiguang132.com/resources/astryx/docs/lightbox
- Resource: Astryx (https://jiguang132.com/resources/astryx.md)
- All guides: https://jiguang132.com/resources/astryx/docs.md

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

```bash
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](/resources/astryx/docs/getting-started).

## 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

```json
{
  "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.

---

Index of all JGuang resources: https://jiguang132.com/llms.txt