Lightbox

Modal image viewer with keyboard navigation across a gallery of images.

Status: alpha. Group: media. Markdown version: /design-system/components/lightbox.md

When to use

Modal image viewer with keyboard navigation across a gallery of images.

When not to use

Do not open a Lightbox from inside a Modal when the images can live on the page; it works (the Lightbox becomes the topmost focus trap and one Escape closes only the Lightbox) but two stacked dialogs are heavier than one.
Do not use it for non-image content. It is sized and captioned for images; use Modal for arbitrary content.

Look-alikes

Modal: Do not use it for non-image content. It is sized and captioned for images; use Modal for arbitrary content.

Props

Lightbox props
Prop	Type	Default	Description	Required
`images`	`LightboxImage[]`	none	No description in the contract.	Yes
`initialIndex`	`number`	`0`	No description in the contract.	No
`open`	`boolean`	`false`	No description in the contract.	No
`onOpenChange`	`(open: boolean) => void`	none	No description in the contract.	No

Variants

No variant dimensions and no props with a fixed set of values.

Invalid combinations

The contract records no invalid combinations.

Keyboard

Lightbox keyboard behaviour
Key	Behaviour
Escape	Closes the lightbox.
ArrowRight	Advances to the next image.
ArrowLeft	Returns to the previous image.
Tab	Cycles through the panel buttons and is trapped inside the dialog.
Shift+Tab	Wraps backwards.

Rules

Every item under When not to use is a MUST NOT. MUST and SHOULD follow RFC 2119.

Lightbox rules
Level	Rule	How it is checked
MUST	ARIA: Role=dialog with aria-modal=true on the panel.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Aria-label is the current image's alt, or "Image gallery" when alt is empty; position is announced by the counter's polite live region, not the name.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Focus moves to the close button on open and returns to the previously focused element on close.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: While open, every page region outside the dialog (header, main, footer and sibling layers) is inert through the shared focus trap, so aria-modal=true matches what is reachable.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: One Escape press calls onOpenChange(false) once; Escape and the arrow keys are ignored while a layer opened above the Lightbox is active.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Re-rendering the parent with a new onOpenChange function does not move focus or toggle inert.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	Required stories produce no axe violations at the configured severity.	Automated by `npm run test:stories:matrix:ci`. WCAG 2.5.8.
MUST	The accessibility tree (role, name, state) matches the committed snapshot for every required story.	Automated by `npm run test:stories:matrix:ci`. WCAG 1.3.1, 4.1.2.
MUST	The component remains legible and operable under a real browser forced-colors: active pass.	Automated by `npm run test:stories:hc`.
MUST	Positional, scale, and opacity motion is suppressed under prefers-reduced-motion.	Manual review, last on 2026-11-04. WCAG 2.2.2, 2.3.3.
MUST	Every documented keyboard interaction works as specified.	Manual review, last on 2026-11-04. WCAG 2.1.1, 2.1.2.

Install and import

In-repo only. Lightbox is not exported from @digitaltableteur/react, so there is no public import path.
Alpha components are internal and never exported.