Lightbox 1.2.2

<velin-lightbox> is a fullscreen media overlay for slotted images and videos. In 1.2.0, open/close uses focus-manager for background inert and scroll lock; close fires velin-close. Deutsch: Lightbox De

Maturity: Documented as stable in VelinStyle 1.2.0. Design Intelligence (plan / review / agent meta) is separate and beta / foundation where noted.

When to use

Image or video galleries where clicking a thumbnail should open a focused overlay viewer.
When you need keyboard prev/next, a live counter, and modal focus behavior out of the box.

When not

Non-media dialogs — use Modal or Dialog.
Do not wrap thumbnails only in <a> without a slotted <img>/<video> — the component collects those tags (or elements with data-velin-lightbox).
Constraint: media must be direct children of <velin-lightbox>. Nested wrappers (<a>, <figure>) are not walked — put <img>/<video> as immediate slotted children.

Basic gallery

Slot <img> (or <video>) children. Clicks call open(index). Optional data-velin-lightbox overrides the full-size URL (sanitized).

<velin-lightbox>
  <img src="photo-thumb-1.jpg"
       data-velin-lightbox="photo-full-1.jpg"
       alt="Mountain lake">
  <img src="photo-thumb-2.jpg"
       data-velin-lightbox="photo-full-2.jpg"
       alt="Dog portrait">
</velin-lightbox>

Keyboard navigation

While open, focus starts on the close button. ← / → change slides, Escape closes, and Tab is trapped in the overlay. A polite live region and announce() report the slide counter.

<!-- Built-in keys: ArrowLeft / ArrowRight / Escape / Tab trap -->
<velin-lightbox>
  <img src="thumb1.jpg" alt="Slide 1">
  <img src="thumb2.jpg" alt="Slide 2">
</velin-lightbox>

Video support

Slot a <video> (or point data-velin-lightbox at a media URL). Video items render with controls and autoplay inside the overlay.

<velin-lightbox>
  <img src="photo-thumb.jpg" alt="Photo">
  <video src="clip.mp4" poster="video-poster.jpg"
         aria-label="Short clip"></video>
</velin-lightbox>

Accessibility

Overlay: role="dialog", aria-modal="true", aria-label="Image lightbox", aria-roledescription="lightbox".
Prev / next / close buttons have accessible names.
Counter uses aria-live="polite" / aria-atomic="true"; slide changes also call announce().
On open: setBackgroundInert(this); on close / disconnect: clearBackgroundInert(this); focus restored.
close() dispatches bubbling velin-close. Backdrop click (overlay target) closes.
Image alt is escaped into the enlarged view; URLs pass through sanitizeURL.

Dark, responsive, motion, RTL

Dark: overlay uses a dark translucent backdrop by design; controls are light on dark.
Responsive: content capped at 90vw / 90vh; nav buttons move inward below 48rem.
Motion: overlay opacity transition disabled under prefers-reduced-motion: reduce.
RTL: absolute prev/next use physical left/right offsets (arrows still follow keyboard Left/Right).

API

Methods & events

API	Description
`open(index = 0)`	Opens at slide index; sets `open`; applies inert
`close()`	Closes, clears inert, restores focus, fires `velin-close`
`velin-close`	Bubbling close event

Slots & parts

Name	Description
Default slot	`IMG`, `VIDEO`, or elements with `data-velin-lightbox`
Parts	`overlay`, `content`, `counter`

CSS variables

Variable	Description
`--velin-z-modal`	Overlay z-index (default 500)
`--velin-radius-md`	Media corner radius
`--velin-color-focus`	Focus outline on controls

Best practices & pitfalls

Always set meaningful alt on images — it is reused in the enlarged view.
There is no data-caption, iframe/YouTube mode, Home/End, or touch-swipe API in the current component.
Prefer data-velin-lightbox when the thumbnail src differs from the full asset.

Carousel — in-page media rotation
Modal — general dialog overlay
Drawer — off-canvas panels