@reelkit/vue-lightbox

@reelkit/vue-lightbox

Full-screen image and video gallery lightbox for Vue 3. Horizontal swipe navigation, fullscreen toggle, opt-in video support, and four built-in transitions. ~4.9 kB gzip.

Live Demo

Installation

npm install @reelkit/vue-lightbox @reelkit/vue lucide-vue-next

Quick Start

<script setup lang="ts">
import { ref } from 'vue';
import { LightboxOverlay, type LightboxItem } from '@reelkit/vue-lightbox';
import '@reelkit/vue-lightbox/styles.css';

const open = ref(false);
const items: LightboxItem[] = [
  {
    src: 'https://example.com/image-01.jpg',
    title: 'Mountain River',
    description: 'A beautiful mountain river flowing through the forest',
    width: 1600,
    height: 1000,
  },
];
</script>

<template>
  <button @click="open = true">Open Gallery</button>
  <LightboxOverlay v-model:is-open="open" :items="items" />
</template>

Features

• Horizontal swipe navigation (touch, mouse, keyboard, wheel)
• Tree-shakable transitions — slideTransition, flipTransition, lightboxFadeTransition, lightboxZoomTransition (import only what you use)
• Fullscreen toggle with two-step Escape (exit fullscreen → close)
• Swipe-up-to-close on mobile
• Opt-in video support via useVideoSlideRenderer
• Opt-in slideshow — auto-advance plays the gallery on its own, with a PlayPauseButton and play() / pause() on the api
• Opt-in download — show-download adds a DownloadButton that saves the active item, from downloadUrl when the preview is a resized copy
• Desktop prev/next arrows with boundary hiding
• Dialog a11y: role="dialog", aria-modal, focus trap + return
• Themeable via --rk-lightbox-* CSS custom properties
• Shareable URLs — LightboxUrlOverlay opens itself from the address bar

Scoped Slots

Props

Events

The LightboxApi from api-ready (also on the template ref) has next(), prev(), goTo(), adjust(), observe(), unobserve(), close(), and play() / pause() for the slideshow.

Slideshow and download (opt-in)

<LightboxOverlay
  v-model:is-open="open"
  :items="items"
  auto-advance
  :auto-advance-interval="4000"
  show-download
/>

auto-advance counts each image's interval from the moment it has loaded, plays a video once and moves on when it ends, waits while the mouse rests on a control, during a swipe and while the page is hidden, and stops on the last slide unless loop is set. A PlayPauseButton joins the controls.

show-download adds a DownloadButton that saves the active item from downloadUrl (or src) under downloadName; a LightboxItem takes both as optional fields. The file is fetched so a cross-origin link still downloads; when the server sends no CORS headers it opens in a new tab instead.

Video support (opt-in)

<script setup lang="ts">
import { ref } from 'vue';
import {
  LightboxOverlay,
  useVideoSlideRenderer,
  type LightboxItem,
} from '@reelkit/vue-lightbox';
import '@reelkit/vue-lightbox/styles.css';

const open = ref(false);
const items: LightboxItem[] = [
  { src: '/image.jpg' },
  { type: 'video', src: '/clip.mp4', poster: '/clip.jpg' },
];
const { VideoSlideRenderer, VideoControlsRenderer, SoundProvider } =
  useVideoSlideRenderer(items);
</script>

<template>
  <SoundProvider>
    <LightboxOverlay v-model:is-open="open" :items="items">
      <template #slide="scope">
        <VideoSlideRenderer v-bind="scope" />
      </template>
      <template #controls="scope">
        <VideoControlsRenderer v-bind="scope" />
      </template>
    </LightboxOverlay>
  </SoundProvider>
</template>

URL-driven lightbox

LightboxUrlOverlay takes the same props except isOpen — the address bar owns the open state, so a shared link opens the gallery on the right image:

<script setup lang="ts">
import { LightboxUrlOverlay, type LightboxItem } from '@reelkit/vue-lightbox';
import { useOverlayUrlState, urlIndexKey } from '@reelkit/vue';
import '@reelkit/vue-lightbox/styles.css';

const props = defineProps<{ images: LightboxItem[] }>();

const photo = useOverlayUrlState({
  param: 'photo',
  ...urlIndexKey(() => props.images.length),
});
</script>

<template>
  <!-- Opening is a link — the overlay reads the URL and opens itself. -->
  <RouterLink
    v-for="(img, i) in props.images"
    :key="img.src"
    :to="`?photo=${i}`"
  >
    <img :src="https://raw.githubusercontent.com/KonstantinKai/reelkit/HEAD/img.src" />
  </RouterLink>

  <LightboxUrlOverlay :controller="photo" :items="props.images" />
</template>

In a vue-router application pass adapter: useVueRouterUrlAdapter() from @reelkit/vue/vue-router-url-adapter, otherwise the router's own location goes stale. Swap urlIndexKey for urlStableIdKey({ items: () => props.images }) to key the URL by image id.

Sub-components

For composing your own controls or slides: CloseButton, Counter, FullscreenButton, SoundButton, PlayPauseButton, DownloadButton, LightboxNavigation, ImageSlide, LightboxVideoSlide.

Keyboard Shortcuts

Documentation

Docs, runnable StackBlitz examples, and customization guides at reelkit.dev/docs/vue-lightbox.

Support

If ReelKit saved you some time, a star on GitHub would mean a lot — it's a small thing, but it really helps the project get noticed.

License

MIT