presentation form · Dialog and side surfaces
Lightbox
A modal overlay that enlarges an image, video, or media to full or near-full viewport size, dimming the page behind it with close, navigation, and caption controls.
Decisive boundary
A lightbox is a modal media viewer. Do not confuse it with a tooltip preview or a non-modal image popover.
Definition and intent
What is a Lightbox UI pattern?
Use the behavior, not the silhouette
A modal overlay that enlarges an image, video, or media to full or near-full viewport size, dimming the page behind it with close, navigation, and caption controls. The term is used here as a presentation form that describes placement or motion without deciding every semantic behavior. That distinction prevents a visual resemblance from silently deciding focus, keyboard, modality, or dismissal behavior.
Let users view media at full resolution without navigating to a separate page. A good implementation preserves that job while making the trigger, open state, close path, and responsive behavior observable to users.
Know when the label is wrong
The fastest way to identify a pattern is often to reject the nearest alternative. For Lightbox, the boundary is: A lightbox is a modal media viewer. Do not confuse it with a tooltip preview or a non-modal image popover.
Do not implement it as Tooltip for image previews, and Non-Modal Dialog for a media surface that must not block the page. If those requirements describe the real task better, use the related pattern page or the full Dialog and side surfaces comparison before writing code.
Decision process
Decide before choosing a component
Record these requirements in plain language. A library component name is not a substitute for the contract.
Confirm the user job
Let users view media at full resolution without navigating to a separate page.
Define opening and closing
Click or Enter on a thumbnail, gallery image, or media preview. Close button, Escape key, or click on the background scrim.
Specify access behavior
Focus moves into the lightbox; close and navigation controls are first in order; focus returns to the invoking thumbnail on close. Escape closes; Tab cycles among controls; Left/Right arrows navigate media when multiple items exist; Enter opens and Space may toggle navigation.
Reject the near miss
Tooltip for image previews, and Non-Modal Dialog for a media surface that must not block the page.
Behavior contract
What must survive the build
- trigger
- Click or Enter on a thumbnail, gallery image, or media preview.
- dismissal
- Close button, Escape key, or click on the background scrim.
- modality
- Modal — background content is inert and visually obscured.
- focus
- Focus moves into the lightbox; close and navigation controls are first in order; focus returns to the invoking thumbnail on close.
- keyboard
- Escape closes; Tab cycles among controls; Left/Right arrows navigate media when multiple items exist; Enter opens and Space may toggle navigation.
- interactive
- Contains close and optional previous/next/caption controls; the media itself may support zoom or play.
- persistence
- Remains until dismissed; does not auto-close.
- placement
- Centered overlay covering most or all of the viewport.
- mobile
- Swipe gestures may navigate media; close button must remain easily reachable; avoid requiring precision taps.
Failure modes
Common wrong builds
- Failing to trap focus inside the lightbox.
- Omitting a visible close button in addition to Escape.
- Hiding the lightbox behind a focus stack without returning focus.
- Not providing alt text or captions for the enlarged media.
Observable checks
Verify the result
- A close button is always visible and reachable.
- Escape closes the lightbox.
- Focus returns to the invoking thumbnail.
- Background content is inert.
- Images maintain their aspect ratio on all screen sizes.
Coding-agent handoff
Implementation brief template
Pattern: Lightbox Purpose: Let users view media at full resolution without navigating to a separate page. Trigger: Click or Enter on a thumbnail, gallery image, or media preview. Dismissal behavior: Close button, Escape key, or click on the background scrim. Modality: Modal — background content is inert and visually obscured. Focus behavior: Focus moves into the lightbox; close and navigation controls are first in order; focus returns to the invoking thumbnail on close. Keyboard behavior: Escape closes; Tab cycles among controls; Left/Right arrows navigate media when multiple items exist; Enter opens and Space may toggle navigation. Interactive content: Contains close and optional previous/next/caption controls; the media itself may support zoom or play. Placement: Centered overlay covering most or all of the viewport. Mobile behavior: Swipe gestures may navigate media; close button must remain easily reachable; avoid requiring precision taps. Do not implement as: Tooltip for image previews, and Non-Modal Dialog for a media surface that must not block the page. Acceptance checks: - A close button is always visible and reachable. - Escape closes the lightbox. - Focus returns to the invoking thumbnail. - Background content is inert. - Images maintain their aspect ratio on all screen sizes.
Claim-level references
Sources, not a confidence score
Frequently asked questions
Lightbox UI pattern questions
Direct answers based on the reviewed behavior contract above.
What is a Lightbox in web UI?
A modal overlay that enlarges an image, video, or media to full or near-full viewport size, dimming the page behind it with close, navigation, and caption controls. In this reference set it is a presentation form that describes placement or motion without deciding every semantic behavior.
When should I use a Lightbox?
Let users view media at full resolution without navigating to a separate page. The decisive boundary to confirm is this: A lightbox is a modal media viewer. Do not confuse it with a tooltip preview or a non-modal image popover.
What keyboard and focus behavior does a Lightbox need?
Escape closes; Tab cycles among controls; Left/Right arrows navigate media when multiple items exist; Enter opens and Space may toggle navigation. Focus moves into the lightbox; close and navigation controls are first in order; focus returns to the invoking thumbnail on close. These statements describe the reviewed expectation, but the final implementation still needs testing in the component library and browser you ship.
How should a Lightbox behave on mobile?
Swipe gestures may navigate media; close button must remain easily reachable; avoid requiring precision taps. Its modality is a separate requirement: Modal — background content is inert and visually obscured.
How do I verify a Lightbox implementation?
Start with observable checks: A close button is always visible and reachable. Escape closes the lightbox. Focus returns to the invoking thumbnail. Then verify the remaining checks and compare the result with the linked source guidance.