Usage
State management and accessible trigger wiring for Lightbox. Eliminates boilerplate for managing open state and current index. Returns trigger props with button role, tabIndex={0}, aria-haspopup="dialog", and keyboard activation handlers, along with a pre-wired Lightbox element that handles dismissal, next/previous navigation, and focus restoration.
ts
Best practices
| Guidance | Practices |
|---|---|
| Do | Spread getTriggerProps(index) onto image or thumbnail elements to give them accessible button semantics and keyboard activation. |
| Do | Render lightbox.element once in your component JSX tree alongside the triggers. |
| Don't | Manage separate isOpen or index state alongside useLightbox; the hook already tracks both. |
| Don't | Add custom click or keydown handlers to open the lightbox when using triggerProps or getTriggerProps. |
Parameters
| Param | Type | Description |
|---|---|---|
optionsrequired | Configuration options for the lightbox. | |
options.mediarequired | | [] | Media to display in the lightbox. Pass a single object for one item, or an array for gallery mode. |
options.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. |
options.hasAutoPlay | boolean (default: false) | Whether video should autoplay when the lightbox opens. |
Returns
| Field | Type | Description |
|---|---|---|
| open | (index?: number) => void | Open the lightbox, optionally at a specific gallery index (defaults to 0). |
| close | () => void | Close the lightbox. |
| isOpen | boolean | Whether the lightbox is currently open. |
| index | number | Current gallery index. |
| element | ReactNode | Pre-wired Lightbox component element to render in your JSX tree. |
| triggerProps | {role: 'button', tabIndex: 0, 'aria-haspopup': 'dialog', onClick: () => void, onKeyDown: (e: React.KeyboardEvent) => void} | Props to spread onto a single trigger element to open the lightbox at index 0 on click, Enter, or Space. |
| getTriggerProps | (index: number) => {role: 'button', tabIndex: 0, 'aria-haspopup': 'dialog', onClick: () => void, onKeyDown: (e: React.KeyboardEvent) => void} | Returns trigger props to spread onto an element to open the lightbox at a specific gallery index on click, Enter, or Space. |
Examples
Common configurations, variations, and states.Photo gallery thumbnail grid using useLightbox for trigger props, keyboard navigation, and open state.
Use with shadcn
Already using the shadcn registry workflow? Install the real Astryx package and a local public re-export. Component implementation source stays in Astryx.
This install URL expires with the draft preview.bash