Vue Lightbox

Features

Installation

Don't forget to import the styles:

Basic Usage

Import the stylesheet and the LightboxOverlay component, then drive open/close with v-model:is-open.

Scoped Slots

Six named scoped slots allow full customisation of the overlay surfaces. Omit the slot to keep the built-in default; provide nothing inside the slot (e.g. via v-if="false") to hide that section entirely.

Video Support

Video slides are opt-in so the default bundle stays free of audio/video wiring. Call useVideoSlideRenderer(items) and forward the returned VideoSlideRenderer / VideoControlsRenderer into the overlay's #slide and #controls slots. Wrap the overlay in the returned SoundProvider so the built-in sound toggle has a context.

Fullscreen

Use useFullscreen from @reelkit/vue to observe or toggle fullscreen state on a referenced element. The lightbox drives its built-in fullscreen button through the same composable.

URL State

Build a controller with useOverlayUrlState from @reelkit/vue and hand it to LightboxUrlOverlay as controller, and the address bar owns the gallery: it opens itself when the parameter names a slide and closes when the parameter goes away. Links are shareable, and the back button closes the gallery. It is a separate component from LightboxOverlay, so each carries exactly one open-state driver — the is-open model or the url controller, never both.

Back closes only when you opened from within the app — the link pushed an entry, so back pops to the gallery. A shared link opened directly in a fresh tab has no history behind it, so browser-back leaves the site; the close button or Escape removes the parameter in place and keeps you on the gallery.

The composable takes one options object and returns a UrlStateController (with set, index, value). Keep it for programmatic control: set is the low-level write the overlay uses internally (slide change, and set(null) to close). It drives the overlay programmatically too — set(index) opens it, the same as navigating to the parameter. Prefer a link for opening though: the href is shareable, opens in a new tab, and the back button closes it — all for free, with no handler.

Full useOverlayUrlState options (param, adapter, codec, locator): see the Vue API reference.

LightboxUrlOverlay itself takes just :controller (required), a @close emit, plus every visual and behavior prop LightboxOverlay forwards (items, transition-fn, the scoped slots, and so on) — but no is-open.

• Opening costs one history entry; paging slides replaces it, so a hundred swipes add none — one back step always leaves the gallery.
• A shared link like ?photo=3 opens the gallery at that slide. A parameter naming no slide is dropped from the URL instead of asserting a slide that cannot open.

In a routed app, pass an adapter. Writing history directly leaves the router's own location stale, and its next navigation drops the parameter.

Stable links. The index is positional, so a bookmark opens a different image once the list is reordered. urlStableIdKey keys by each item's stable id, scanning the live list — one call covers the common case.

Pass hashCodec: base64UrlCodec to base64url-encode the id in the URL — reversible obfuscation, not a cryptographic hash.

Key by a different field (a slug), or page an infinite feed with locateAsync, and build the codec/locator yourself: codec spells the identity into the URL, locator finds where it now sits.

Infinite / paginated galleries. locate is synchronous, so it can only answer for items already loaded — a shared link to image 400 of a feed that has loaded 20 comes up empty. locateAsync is the fallback, called only when it misses: load the pages you need, then return the index the identity turned out to have.

While it is pending the lightbox stays closed and the parameter is left alone, so the deep link survives the fetch. null or a rejection drops the parameter. An answer arriving after the URL moved on, after a close, or after unmount is discarded, so a slow fetch cannot open a slide nobody asked for. Whatever it returns is authoritative — it reports the index of data it just fetched, and the lightbox takes it as-is rather than re-reading items, which Vue has not re-rendered yet.

API Reference

LightboxOverlay Props

LightboxOverlayProps

LightboxUrlOverlay Props

LightboxUrlOverlayProps

Takes every visual and behaviour prop above except is-open, and replaces it with a controller. It emits close, slide-change and api-ready, but no update:is-open. initial-index is ignored here — the controller's position picks the slide, so a value passed alongside it would be overwritten on every open.

LightboxOverlay Events

LightboxItem Interface

Slot Scope Types

Transitions

Pass any TransitionTransformFn via the transition-fn prop. Importing only the transition you use lets the bundler tree-shake the rest. Defaults to slideTransition when omitted.

Content Loading & Error Handling

When you take over rendering via the #slide slot, three lifecycle callbacks are available on the slot scope to report loading state. The lightbox tracks per-slide state and shows a spinner or error icon accordingly. A content preloader caches broken URLs so revisiting a failed slide skips the retry.

Lifecycle callbacks

Wiring callbacks in #slide

Custom loading slot

Use the #loading slot to replace the default spinner.

Custom error slot

Use the #error slot to replace the default broken-image icon.

CSS Classes

All CSS classes are plain (not scoped), so they can be targeted with higher-specificity selectors in a stylesheet loaded after @reelkit/vue-lightbox/styles.css. For color, size, and z-index changes, prefer the CSS custom properties documented in the Theming section below.

Theming

Override any --rk-lightbox-* CSS custom property on :root (or any ancestor of .rk-lightbox-overlay) to retheme. Direct declarations on .rk-lightbox-overlay would shadow inherited values, so keep overrides on an ancestor selector.

Accessibility

The overlay root is a modal dialog (role="dialog", aria-modal="true"). Set the aria-label prop to change the screen-reader announcement; it defaults to "Image gallery". Each slide carries role="group", aria-roledescription="slide", and an aria-label derived from the position (e.g. "Image 2 of 5").

The lightbox captures focus on open and returns it to the trigger on close. Tab and Shift+Tab cycle through focusable elements inside; focus that escapes (click outside, programmatic focus) gets pulled back. Implemented with captureFocusForReturn and createFocusTrap from @reelkit/vue.