@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.0 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
• Desktop prev/next arrows with boundary hiding
• Dialog a11y: role="dialog", aria-modal, focus trap + return
• Themeable via --rk-lightbox-* CSS custom properties

Scoped Slots

Slot	Scope
slide	item, index, size, isActive, onReady, onWaiting, onError
controls	item, activeIndex, count, isFullscreen, onClose, onToggleFullscreen
navigation	item, activeIndex, count, onPrev, onNext
info	item, index
loading	item, activeIndex
error	item, activeIndex

Props

Prop	Type	Default	Description
isOpen	boolean	required	Controls overlay visibility
items	LightboxItem[]	required	Images/videos to display
initialIndex	number	0	Starting slide index
ariaLabel	string	'Image gallery'	Dialog aria-label
transitionFn	TransitionTransformFn	slideTransition	Slide transition fn (built-in or custom)
loop	boolean	false	Enable infinite loop
enableNavKeys	boolean	true	Arrow-key navigation
enableWheel	boolean	true	Wheel navigation
showInfo	boolean	true	Show title/description overlay
showControls	boolean	true	Show controls bar
showNavigation	boolean	true	Show prev/next arrows on desktop

Events

Event	Payload	Description
close	void	Emitted when the overlay closes
slide-change	number	Emitted after the active slide changes
api-ready	ReelApi	Emitted with the imperative slider API
update:is-open	boolean	Emitted on close — enables v-model:is-open

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 { renderSlide, renderControls, SoundProvider } =
  useVideoSlideRenderer(items);
</script>

<template>
  <SoundProvider>
    <LightboxOverlay v-model:is-open="open" :items="items">
      <template #slide="scope">
        <component :is="renderSlide(scope)" />
      </template>
      <template #controls="scope">
        <component :is="renderControls(scope)" />
      </template>
    </LightboxOverlay>
  </SoundProvider>
</template>

Keyboard Shortcuts

Key	Action
ArrowLeft	Previous slide
ArrowRight	Next slide
Escape	Exit fullscreen (if active), then close the lightbox

Documentation

Docs and interactive demos 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