Vue Lightbox

Lightbox für Bilder- und Videogalerien im Vollbild für Vue 3, gebaut auf @reelkit/vue-lightbox.

Funktionen

Installation

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

Vergiss nicht, die Styles zu importieren:

import '@reelkit/vue-lightbox/styles.css';

Schnellstart

Importiere das Stylesheet und die Komponente LightboxOverlay und steuere Öffnen und Schließen mit v-model:is-open.

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

const images: LightboxItem[] = [
  {
    src: '/cdn/samples/images/image-01.jpg',
    title: 'Mountain River',
    description: 'A beautiful mountain river',
  },
  {
    src: '/cdn/samples/images/image-02.jpg',
    title: 'Snowy Peaks',
  },
  {
    src: '/cdn/samples/images/image-03.jpg',
    title: 'Misty Forest',
    description: 'Morning fog over the forest canopy',
  },
  {
    src: '/cdn/samples/images/image-04.jpg',
    title: 'Autumn Trail',
  },
  {
    src: '/cdn/samples/images/image-05.jpg',
    title: 'Ocean Cliff',
    description: 'Dramatic cliffs above the Pacific',
  },
  {
    src: '/cdn/samples/images/image-06.jpg',
    title: 'Desert Dunes',
  },
];

const open = ref(false);
const startIndex = ref(0);

function openAt(i: number) {
  startIndex.value = i;
  open.value = true;
}
</script>

<template>
  <div style="display:grid;grid-template-columns:repeat(3,1fr);gap:8px">
    <button
      v-for="(img, i) in images"
      :key="img.src"
      style="aspect-ratio:4/3;cursor:pointer"
      @click="openAt(i)"
    >
      <img :src="img.src" style="width:100%;height:100%;object-fit:cover" />
    </button>
  </div>

  <LightboxOverlay
    v-model:is-open="open"
    :items="images"
    :initial-index="startIndex"
  />
</template>

Scoped Slots

Mit sechs benannten Scoped Slots lässt sich jede Fläche des Overlays anpassen. Lass einen Slot weg, um den eingebauten Standard zu behalten; gib im Slot nichts aus (zum Beispiel mit v-if="false"), um diesen Bereich ganz auszublenden.

<template>
  <LightboxOverlay v-model:is-open="open" :items="items">
    <!-- Custom info overlay -->
    <template #info="{ item }">
      <div class="my-caption">
        <h2>{{ item.title }}</h2>
        <p>{{ item.description }}</p>
      </div>
    </template>

    <!-- Custom navigation -->
    <template #navigation="{ onPrev, onNext, activeIndex, count }">
      <div class="my-nav">
        <button :disabled="activeIndex === 0" @click="onPrev">Prev</button>
        <span>{{ activeIndex + 1 }} / {{ count }}</span>
        <button :disabled="activeIndex === count - 1" @click="onNext">Next</button>
      </div>
    </template>

    <!-- Custom controls -->
    <template #controls="{ onClose, isFullscreen, onToggleFullscreen }">
      <div class="my-controls">
        <button @click="onToggleFullscreen">
          {{ isFullscreen ? 'Exit Fullscreen' : 'Enter Fullscreen' }}
        </button>
        <button @click="onClose">Close</button>
      </div>
    </template>
  </LightboxOverlay>
</template>

Video-Unterstützung

Video-Slides sind optional, damit das Standard-Bundle frei von Audio- und Video-Logik bleibt. Rufe useVideoSlideRenderer(items) auf und gib die zurückgegebenen VideoSlideRenderer / VideoControlsRenderer an die Slots #slide und #controls des Overlays weiter. Umschließe das Overlay mit dem zurückgegebenen SoundProvider, damit der eingebaute Ton-Schalter einen Kontext hat. Das zurückgegebene Objekt hat den Typ UseVideoSlideRendererResult: SoundProvider, hasVideo, VideoSlideRenderer und VideoControlsRenderer.

<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-01.jpg', title: 'Image' },
  {
    type: 'video',
    src: '/clip.mp4',
    poster: '/clip.jpg',
    title: 'Clip',
  },
];

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>

Vollbild

Mit useFullscreen aus @reelkit/vue beobachtest oder schaltest du den Vollbildzustand eines referenzierten Elements. Die Lightbox steuert ihren eingebauten Vollbild-Button über dasselbe Composable.

<script setup lang="ts">
import { shallowRef } from 'vue';
import { useFullscreen } from '@reelkit/vue';

const containerRef = shallowRef<HTMLDivElement | null>(null);
const { isFullscreen, toggle } = useFullscreen({ elementRef: containerRef });
</script>

<template>
  <div ref="containerRef">
    <button @click="toggle">
      {{ isFullscreen.value ? 'Exit fullscreen' : 'Enter fullscreen' }}
    </button>
  </div>
</template>

URL-State

Erzeuge mit useOverlayUrlState aus @reelkit/vue einen Controller und gib ihn als controller an LightboxUrlOverlay, dann gehört die Galerie der Adresszeile: Die Galerie öffnet sich, sobald der Parameter einen Slide nennt, und schließt sich, wenn der Parameter verschwindet. Links lassen sich teilen, und der Zurück-Button schließt die Galerie. Die Komponente ist von LightboxOverlay getrennt, damit jede genau einen Treiber für den Öffnungszustand hat — das Model is-open oder den URL-controller, nie beide.

Zurück schließt nur, wenn du aus der App heraus geöffnet hast — der Link hat einen Eintrag angelegt, also führt Zurück wieder zur Galerie. Ein geteilter Link, der direkt in einem neuen Tab geöffnet wird, hat keinen Verlauf dahinter, also verlässt Zurück im Browser die Seite; der Schließen-Button oder Escape entfernt den Parameter an Ort und Stelle und lässt dich auf der Galerie.

<script setup lang="ts">
import { LightboxUrlOverlay, type LightboxItem } from '@reelkit/vue-lightbox';
import { useOverlayUrlState, urlIndexKey, urlStableIdKey } 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 href is the open action. No open flag, no
       handler: the overlay reads the URL and opens itself. -->
  <RouterLink v-for="(img, i) in props.images" :key="img.src" :to="`?photo=${i}`">
    <img :src="img.src" />
  </RouterLink>

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

Das Composable nimmt ein Options-Objekt und gibt einen UrlStateController zurück (mit set, index, value). Behalte ihn für die Steuerung aus dem Code: set ist der Schreibzugriff auf unterster Ebene, den das Overlay intern nutzt (Slide-Wechsel und set(null) zum Schließen). Damit steuerst du das Overlay auch selbst — set(index) öffnet es, genau wie die Navigation zum Parameter. Zum Öffnen ist ein Link trotzdem besser: Der href lässt sich teilen, öffnet sich in einem neuen Tab, und der Zurück-Button schließt ihn — alles ohne Handler.

Alle Optionen von useOverlayUrlState (param, adapter, codec, locator): siehe die API-Referenz für Vue.

LightboxUrlOverlay selbst nimmt nur :controller (Pflicht), ein Emit @close sowie jedes Prop für Darstellung und Verhalten, das LightboxOverlay weitergibt (items, transition-fn, die Scoped Slots und so weiter) — aber kein is-open.

• Das Öffnen kostet einen Verlaufseintrag; das Blättern ersetzt ihn, also fügen hundert Wischgesten keinen hinzu — ein Schritt zurück verlässt die Galerie immer.
• Ein geteilter Link wie ?photo=3 öffnet die Galerie bei diesem Slide. Ein Parameter, der keinen Slide nennt, wird aus der URL entfernt, statt einen Slide zu behaupten, der sich nicht öffnen lässt.

In einer App mit Router übergib einen Adapter. Wer direkt in den Verlauf schreibt, lässt die Location des Routers veralten, und seine nächste Navigation verwirft den Parameter.

<script setup lang="ts">
import { useVueRouterUrlAdapter } from '@reelkit/vue/vue-router-url-adapter';

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

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

Stabile Links. Der Index ist positionsbasiert, also öffnet ein Lesezeichen ein anderes Bild, sobald die Liste neu sortiert wird. urlStableIdKey verwendet die stabile id jedes Elements und durchsucht die aktuelle Liste — ein Aufruf deckt den üblichen Fall ab.

<script setup lang="ts">
const photo = useOverlayUrlState({
  param: 'photo',
  ...urlStableIdKey({ items: () => images }),
});
</script>

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

Übergib hashCodec: base64UrlCodec, um die id in der URL als base64url zu kodieren — eine umkehrbare Verschleierung, kein kryptografischer Hash.

Willst du nach einem anderen Feld (einem slug) adressieren oder einen endlosen Feed mit locateAsync nachladen, baust du codec/locator selbst: codec schreibt die Identität in die URL, locator findet, wo sie jetzt steht.

<script setup lang="ts">
const photo = useOverlayUrlState({
  param: 'photo',
  codec: { decode: (raw) => raw, encode: (id) => id },
  locator: {
    locate: (id) => images.findIndex((x) => x.slug === id),
    identify: (index) => images[index].slug,
  },
});
</script>

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

Endlose / paginierte Galerien. locate ist synchron und kann daher nur für bereits geladene Elemente antworten — ein geteilter Link auf Bild 400 eines Feeds, der 20 geladen hat, findet nichts. locateAsync ist der Rückfall, der nur bei einem Fehlschlag aufgerufen wird: Lade die Seiten, die du brauchst, und gib dann den Index zurück, den die Identität tatsächlich hat.

<script setup lang="ts">
const photo = useOverlayUrlState({
  param: 'photo',
  codec: { decode: (raw) => raw, encode: (id) => id },
  locator: {
    locate: (id) => items.value.findIndex((x) => x.id === id),
    identify: (index) => items.value[index].id,
    locateAsync: async (id) => {
      const loaded = await loadById(id); // or loadUntil(id) — fetch just that one, or page up to it
      if (!loaded) return null; // exhausted — link names no item
      items.value = loaded; // commit; the overlay renders from this
      return loaded.findIndex((x) => x.id === id); // wherever it landed
    },
  },
});
</script>

<template>
  <LightboxUrlOverlay :controller="photo" :items="items" />
</template>

Solange die Antwort aussteht, bleibt die Lightbox geschlossen und der Parameter unangetastet, damit der Deep Link das Laden übersteht. null oder eine Ablehnung entfernt den Parameter. Eine Antwort, die eintrifft, nachdem die URL weitergewandert ist, nach dem Schließen oder nach dem Unmount, wird verworfen, damit ein langsamer Abruf keinen Slide öffnet, den niemand angefragt hat. Was sie zurückgibt, ist maßgeblich — sie meldet den Index von Daten, die sie gerade geladen hat, und die Lightbox übernimmt ihn unverändert, statt items erneut zu lesen, das Vue noch nicht neu gerendert hat.

Automatisches Weiterschalten

Setze auto-advance, damit die Galerie beim Öffnen als Diashow läuft. Standardmäßig aus, also rendert und verhält sich eine bestehende Lightbox wie bisher.

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

const open = ref(false);
const lightbox = ref<LightboxApi | null>(null);
</script>

<template>
  <LightboxOverlay
    ref="lightbox"
    v-model:is-open="open"
    :items="items"
    auto-advance
    :auto-advance-interval="4000"
  />
  <!-- The template ref drives it from outside: lightbox?.pause() -->
</template>

• Bilder bleiben für auto-advance-interval stehen (standardmäßig 5000 ms), gezählt ab dem Moment, in dem das Bild geladen ist, damit ein langsames Bild nie übersprungen wird, bevor es jemand gesehen hat. Ein Bild, das nicht lädt, zählt ab seinem Fehler.
• Videos laufen einmal statt in Schleife und schalten weiter, wenn sie enden. VideoSlideRenderer erledigt das für dich; ein eigener #slide liest autoAdvance aus seinem Scope und meldet das Ende über onEnded.
• Sie wartet, solange die Maus auf einem Control ruht (einem Button, einem Link oder der Bildunterschrift), während einer Wischgeste und solange die Seite verborgen ist, und läuft dann dort weiter, wo sie angehalten hat.
• Wechselst du von Hand (Pfeile, Tasten, Mausrad, Wischen), beginnt das Intervall des neuen Slides bei null; die Diashow bleibt an.
• Auf dem letzten Slide hält sie an, außer loop ist gesetzt. Der Play/Pause-Button in den Controls zeigt den Zustand und lässt die Betrachtenden ihn umschalten; play() und pause() an der LightboxApi tun dasselbe aus dem Code.

Ein eigener Slot #controls erhält isAutoAdvancing und, nur wenn auto-advance an ist, onToggleAutoAdvance — rendere einen PlayPauseButton, wenn es vorhanden ist. Das Timing selbst ist createSlideshowController aus @reelkit/core; siehe den Leitfaden zu Autoplay und die Core-API.

Download

Setze show-download, um den Controls einen Download-Button hinzuzufügen. Er speichert das aktive Element aus seiner downloadUrl, ersatzweise aus src, unter seinem downloadName, ersatzweise unter dem letzten Segment der URL.

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

const open = ref(false);
const items: LightboxItem[] = [
  {
    src: 'https://cdn.example.com/beach-1600.jpg',
    // Save the original rather than the resized preview
    downloadUrl: 'https://cdn.example.com/beach-original.jpg',
    downloadName: 'beach.jpg',
  },
];
</script>

<template>
  <LightboxOverlay v-model:is-open="open" :items="items" show-download>
    <!-- A custom bar shows the buttons only when their handler is there -->
    <template #controls="{ onClose, isDownloading, onDownload }">
      <DownloadButton
        v-if="onDownload"
        :is-downloading="isDownloading"
        :on-press="onDownload"
      />
      <CloseButton :on-press="onClose" />
    </template>
  </LightboxOverlay>
</template>

Die Datei wird abgerufen und gespeichert, weil ein Browser das Attribut download an einem Link auf einen anderen Origin ignoriert und die Datei stattdessen öffnen würde. Schlägt der Abruf fehl — meist ein Server auf einem anderen Origin, der keine CORS-Header sendet —, öffnet sich die Datei in einem neuen Tab, wo man sie trotzdem speichern kann. Liefere die Dateien mit Access-Control-Allow-Origin aus, damit ein Klick zum Speichern genügt. Während ein Download läuft, ist der Button deaktiviert.

Ein eigener Slot #controls erhält isDownloading und, nur wenn show-download an ist, onDownload — rendere einen DownloadButton, wenn es vorhanden ist. Der Helfer ist downloadFile aus @reelkit/core; siehe den Leitfaden zum Download.

Control-Buttons

Teile für Slides und Navigation

API-Referenz

Props von LightboxOverlay

LightboxOverlayProps

Props von LightboxUrlOverlay

LightboxUrlOverlayProps

Nimmt jedes Prop für Darstellung und Verhalten von oben außer is-open und ersetzt es durch einen controller. Es sendet close, slide-change und api-ready, aber kein update:is-open. initial-index wird hier ignoriert — die Position des Controllers wählt den Slide, also würde ein daneben übergebener Wert bei jedem Öffnen überschrieben.

Events von LightboxOverlay

LightboxApi

Das Objekt, das api-ready sendet, auch über die Template-Ref der Komponente verfügbar. Der Slider existiert nur, solange das Overlay offen ist, also tut jede Slider-Methode im geschlossenen Zustand nichts; close() funktioniert immer.

Interface LightboxItem

Typen der Slot-Scopes

Übergänge

Übergib eine beliebige TransitionTransformFn über das Prop transition-fn. Importierst du nur den Übergang, den du nutzt, kann der Bundler den Rest per Tree-Shaking entfernen. Ohne Angabe gilt slideTransition.

<script setup lang="ts">
import {
  LightboxOverlay,
  lightboxFadeTransition,
  lightboxZoomTransition,
} from '@reelkit/vue-lightbox';
</script>

<template>
  <!-- Built-in transition -->
  <LightboxOverlay
    v-model:is-open="open"
    :items="items"
    :transition-fn="lightboxFadeTransition"
  />

  <!-- Different built-in -->
  <LightboxOverlay
    v-model:is-open="open"
    :items="items"
    :transition-fn="lightboxZoomTransition"
  />
</template>

Laden von Inhalten und Fehlerbehandlung

Wenn du das Rendern über den Slot #slide übernimmst, stehen im Slot-Scope drei Lifecycle-Callbacks bereit, um den Ladezustand zu melden. Die Lightbox verfolgt den Zustand jedes Slides und zeigt entsprechend einen Spinner oder ein Fehlersymbol. Ein Preloader merkt sich defekte URLs, damit ein erneuter Besuch eines fehlgeschlagenen Slides keinen neuen Versuch startet.

Lifecycle-Callbacks

Callbacks in #slide verdrahten

<template>
  <LightboxOverlay v-model:is-open="open" :items="items">
    <template
      #slide="{ item, size, isActive, onReady, onWaiting, onError }"
    >
      <template v-if="item.type === 'video'">
        <video
          :src="item.src"
          :poster="item.poster"
          :autoplay="isActive"
          :style="{ width: `${size[0]}px`, height: `${size[1]}px`, objectFit: 'contain' }"
          @canplay="onReady"
          @waiting="onWaiting"
          @error="onError"
        />
      </template>
      <template v-else>
        <img
          :src="item.src"
          :style="{ width: `${size[0]}px`, height: `${size[1]}px`, objectFit: 'contain' }"
          @load="onReady"
          @error="onError"
        />
      </template>
    </template>
  </LightboxOverlay>
</template>

Eigener Lade-Slot

Mit dem Slot #loading ersetzt du den Standard-Spinner.

<template>
  <LightboxOverlay v-model:is-open="open" :items="items">
    <template #loading="{ item, activeIndex }">
      <div class="my-loading">
        <span>Loading image {{ activeIndex + 1 }}…</span>
        <span class="muted">{{ item.title }}</span>
      </div>
    </template>
  </LightboxOverlay>
</template>

Eigener Fehler-Slot

Mit dem Slot #error ersetzt du das Standard-Symbol für ein defektes Bild.

<template>
  <LightboxOverlay v-model:is-open="open" :items="items">
    <template #error="{ item, activeIndex }">
      <div class="my-error">
        <span>Failed to load</span>
        <span class="muted">{{ item.title ?? item.src }}</span>
      </div>
    </template>
  </LightboxOverlay>
</template>

CSS-Klassen

Alle CSS-Klassen sind normal (nicht scoped), also lassen sie sich mit spezifischeren Selektoren in einem Stylesheet ansprechen, das nach @reelkit/vue-lightbox/styles.css geladen wird. Für Farben, Größen und z-index nimm lieber die CSS Custom Properties aus dem Abschnitt Theming weiter unten.

Theming

Überschreibe eine beliebige CSS Custom Property --rk-lightbox-* auf :root (oder einem Vorfahren von .rk-lightbox-overlay), um das Aussehen anzupassen. Direkte Deklarationen auf .rk-lightbox-overlay würden geerbte Werte überdecken, also setze Überschreibungen auf einem Vorfahren-Selektor.

<style>
:root {
  --rk-lightbox-overlay-bg: #0f172a;
  --rk-lightbox-btn-bg: rgba(99, 102, 241, 0.65);
  --rk-lightbox-btn-bg-hover: rgba(168, 85, 247, 0.85);
  --rk-lightbox-info-bg: linear-gradient(
    transparent,
    rgba(99, 102, 241, 0.55) 60%,
    rgba(168, 85, 247, 0.85)
  );
}
</style>

Barrierefreiheit

Die Wurzel des Overlays ist ein modaler Dialog (role="dialog", aria-modal="true"). Mit dem Prop aria-label änderst du die Ansage für Screenreader; Standard ist "Image gallery". Jeder Slide trägt role="group", aria-roledescription="slide" und ein aus der Position abgeleitetes aria-label (zum Beispiel "Image 2 of 5").

Die Lightbox übernimmt beim Öffnen den Fokus und gibt ihn beim Schließen an den Auslöser zurück. Tab und Shift+Tab wechseln zwischen den fokussierbaren Elementen darin; Fokus, der entwischt (Klick außerhalb, Fokus aus dem Code), wird zurückgeholt. Umgesetzt mit captureFocusForReturn und createFocusTrap aus @reelkit/vue.

Tastenkürzel