React Image Lightbox: Zoom, Wischen, Ziehen zum Schließen

Du hast ein Raster mit Fotos und willst eine React Image Lightbox: Foto antippen, im Vollbild ansehen, zum nächsten wischen, in ein Detail zoomen. Der einfache Fall ist schnell gebaut. Dann taucht das Foto aus dem Nichts auf, statt aus der Kachel zu wachsen, der Rahmen springt, wenn die Datei ankommt, ein Pinch zoomt die ganze Seite, ein Wisch nach unten bewirkt am Smartphone nichts, und nach dem Schließen landet der Tastaturfokus ganz oben im Dokument. Dieser Guide zeigt, was eine Lightbox im echten Einsatz können muss, welche Props in der Image Lightbox von Wingo UI zählen und wann die Product Gallery besser passt.

Was muss eine React Image Lightbox können?

Aus dem Thumbnail öffnen, pro Wisch ein Foto weiterblättern, dort zoomen, wo der Nutzer hinzeigt, sich so schließen wie die Foto-App am Smartphone und dabei Tastatur- und Screenreader-Nutzern die Orientierung lassen. An dieser Liste messen wir unseren eigenen Viewer:

1. Beim Öffnen aus dem Thumbnail wachsen und beim Schließen zurück in die Kachel des aktuellen Fotos fliegen.
2. Zwischen Fotos wischen, eins pro Wisch, am Desktop mit Pfeilen und einem Thumbnail-Streifen.
3. Zoomen per Pinch, Doppeltipp oder Trackpad-Pinch und das Foto mit Schwung verschieben.
4. Auf Touchscreens mit einem Wisch nach unten schließen.
5. Kein Layout Shift beim Laden der Bilder, und nicht alle Dateien in voller Größe vorab laden.
6. Tastatur und Fokus: Pfeiltasten, Escape, eine Focus Trap, und beim Schließen geht der Fokus an das Thumbnail des Fotos, das gerade zu sehen ist.

Welche React Lightbox Libraries werden noch gepflegt?

Yet Another React Lightbox bekommt weiterhin Releases: Version 3.32.2 kam im Juli 2026 auf npm. Das letzte Release von PhotoSwipe ist 5.4.4 vom Mai 2024, und laut README ist v6 in Arbeit. Das Paket, das tatsächlich react-image-lightbox heißt, wurde am 19. Januar 2023 archiviert, und sein README verweist stattdessen auf react-photoswipe-gallery. Die Angaben unten stammen aus Doku, README und npm-Seite der Projekte, Stand Oktober 2026.

PhotoSwipe ist eine gute Wahl, wenn du einen ausgereiften Viewer ohne Framework-Bindung willst und ihn selbst in React einbindest; die Doku hat eine eigene Seite zur Animation aus einem beschnittenen Thumbnail. Yet Another React Lightbox passt, wenn du ein React-Paket mit Zoom und Thumbnails als optionalen Plugins suchst. Falls du nach einer shadcn Lightbox gesucht hast: shadcn/ui hat keine. Es liefert ein Carousel auf Basis von Embla (opens in a new tab) und einen Dialog, und die beiden kombinierst du selbst. Der Viewer von Wingo UI ist genau diese Kombination, fertig gebaut: ein Carousel auf Basis von Embla in einem Radix-Dialog-Primitive (demselben, das unser Dialog nutzt), mit den Gesten obendrauf.

Welche Props braucht die Image Lightbox?

Nur eine: images, ein Array aus { src, alt, caption?, width?, height?, srcSet?, sizes?, thumbnail?, downloadName? }. Am schnellsten kommst du mit LightboxGallery zu einer React Lightbox Galerie: Sie rendert ein Raster aus Thumbnail-Buttons und macht jede Kachel zum Ursprung, aus dem ihr Foto herausfliegt.

npx wingo-ui@latest add image-lightbox

"use client";

import { LightboxGallery, type LightboxImage } from "@/components/ui/image-lightbox";

const photos: LightboxImage[] = [
  { src: "/photos/living.jpg", alt: "Helles Wohnzimmer", caption: "Helles Wohnzimmer, 260 sq ft", width: 960, height: 600 },
  { src: "/photos/sofa.jpg", alt: "Grünes Samtsofa", caption: "Samtsofa, bleibt in der Wohnung", width: 960, height: 600 },
  { src: "/photos/desk.jpg", alt: "Schreibtischecke am Fenster", caption: "Schreibtischecke am Fenster", width: 960, height: 600 },
  { src: "/photos/parking.jpg", alt: "Tiefgaragenstellplatz", caption: "Stellplatz in der Miete enthalten", width: 960, height: 600 },
];

export function ListingPhotos() {
  return <LightboxGallery images={photos} columns={{ base: 2, md: 4 }} featured maxVisible={5} />;
}

featured lässt die erste Kachel 2 mal 2 Felder einnehmen, und maxVisible={5} macht aus der fünften Kachel ein „+N“, wenn es mehr Fotos gibt. Standardmäßig hat das Raster 2 Spalten, ab 640px 3 und ab 768px 4, mit quadratischen Kacheln und 12px Eckenradius; das änderst du mit aspect, gap und radius.

Gib jedem Bild width und height mit, damit der Rahmen die Form des Fotos annimmt, bevor die Datei lädt, und eine kleine thumbnail-Datei für das Raster, den Streifen und den Platzhalter beim Laden. Es laden nur das aktuelle Foto und seine Nachbarn, und ein Spinner liegt über dem Platzhalter, bis die Datei bereit ist.

Als Nächstes brauchst du meist zoom (standardmäßig an), maxZoom (4), doubleTapZoom (2.5), loop (aus), download und share (beide aus) und hideControlsDelay, das die Toolbar am Desktop nach 3000ms ohne Mausbewegung ausblendet. Alle Texte stecken in labels; was du dort angibst, überschreibt die Werte aus DEFAULT_IMAGE_LIGHTBOX_LABELS.

Wie zoomt die Lightbox aus ihrem Thumbnail heraus?

Der Viewer misst das Element, aus dem das Foto kommt, startet das Foto in genau diesem Rechteck mit demselben Ausschnitt und Eckenradius und animiert es mit einer Spring-Animation auf die eingepasste Größe. LightboxGallery verdrahtet das für dich. Für ein eigenes Layout, etwa ein großes Titelfoto mit einem separaten Thumbnail-Streifen, nimmst du ImageLightbox direkt, mit einem trigger und einem getOrigin, das für jeden Index das passende Element liefert:

"use client";

import { useRef, useState } from "react";
import { ImageLightbox, type LightboxImage } from "@/components/ui/image-lightbox";

export function CoverPhoto({ photos }: { photos: LightboxImage[] }) {
  const [index, setIndex] = useState(0);
  const cover = useRef<HTMLButtonElement>(null);

  return (
    <ImageLightbox
      images={photos}
      index={index}
      onIndexChange={setIndex}
      // zurück ins Titelfoto schließen, egal welches Foto gerade zu sehen ist
      getOrigin={() => cover.current}
      trigger={
        <button ref={cover} type="button" aria-label={`${photos[index].alt} öffnen`} className="block w-full overflow-hidden rounded-2xl">
          <img src={photos[index].src} alt="" className="aspect-[16/10] w-full object-cover" />
        </button>
      }
    />
  );
}

Weil index kontrolliert ist, folgt das Titelfoto dem Foto, zu dem der Nutzer gewischt hat, und der Viewer schließt sich zurück in das richtige Bild. In einer LightboxGallery mit eigenen Children gibt dir der Hook useLightbox die Funktion open(index, origin): Ruf open(2, event.currentTarget) in einem beliebigen Button auf, und Foto 3 zoomt aus ihm heraus; nach dem Schließen landet der Fokus wieder dort.

Ist reduzierte Bewegung eingestellt, blendet der Viewer nur über, statt zu fliegen (siehe den Guide zu prefers-reduced-motion).

Wie funktionieren Wischen, Pinch-Zoom und Swipe to Close am Smartphone?

Am Smartphone füllt der Viewer den ganzen Bildschirm, schwarz mit weißen Bedienelementen in beiden Themes, und hält mit env(safe-area-inset-*) Abstand zu Notch und Home-Indikator. Ein Tipp blendet die Bedienelemente ein und aus.

• Seitlich wischen blättert, mit der Physik von Embla.
• Pinch zoomt um deine Finger herum. Unter 1x und über maxZoom gibt es Widerstand, dann pendelt sich der Zoom ein. Ein Doppeltipp zoomt an der angetippten Stelle auf doubleTapZoom, ein zweiter Doppeltipp wieder zurück.
• Bei gezoomtem Foto verschiebt ein Wisch das Foto, statt zu blättern, und Swipe to Close ist aus. Beim Fotowechsel wird der Zoom zurückgesetzt.
• Nach unten ziehen auf einem nicht gezoomten Foto lässt es Richtung 0.85 schrumpfen, während das Schwarz ausblendet und die Seite durchscheint. Lässt du nach mehr als einem Viertel der Bildschirmhöhe los oder wischst schneller als 400px pro Sekunde, schließt sich der Viewer; sonst federt er zurück.

Nach Jahren mit nativen Foto-Apps erwarten Nutzer, dass sich ein Foto per Ziehen schließen lässt. Deshalb ist der Schließen-Button hier nur die Ausweichlösung und die Geste der eigentliche Weg hinaus. Setz swipeToClose={false}, wenn der Viewer über etwas liegt, das schon vertikales Ziehen nutzt. Der Guide zum React Bottom Sheet behandelt dasselbe Drag-to-Dismiss-Muster für Panels.

Wie mache ich eine Image Lightbox barrierefrei?

Behandle sie als modalen Dialog. Der Viewer baut auf dem Radix-Dialog-Primitive auf, also bleibt der Fokus darin gefangen, solange er offen ist. Beim Schließen geht der Fokus an die Kachel des Fotos, das gerade zu sehen ist, oder zurück an das Element, das den Viewer geöffnet hat, wenn diese Kachel nicht fokussierbar ist. Der versteckte Dialogtitel ist standardmäßig „Image viewer“, die aktuelle Bildunterschrift beschreibt den Dialog, und der Zähler „3 / 8“ ist eine Live-Region im Modus „polite“. Ein Screenreader sagt also jeden Bildwechsel an.

Tasten: Pfeil links und rechts für das vorherige und nächste Foto, Home und End (Pos1 und Ende) für das erste und letzte, + oder = zum Hineinzoomen, - zum Herauszoomen, 0 zum Zurücksetzen. Escape setzt zuerst einen Zoom zurück und schließt erst beim zweiten Drücken, damit jemand, der versehentlich hineingezoomt hat, seine Stelle nicht verliert. Jede Kachel von LightboxGallery ist ein echter Button, dessen Name sich aus labels.openImage und dem alt des Bildes zusammensetzt. Schreib also echte Alt-Texte.

Wann nehme ich stattdessen die Product Gallery?

Auf einer Produkt- oder Inseratseite, auf der die Fotos der Hauptinhalt sind. Die Product Gallery ist eine fertige Komponente für das, was viele als „Product Gallery React“ suchen: eine wischbare Bühne, eine Thumbnail-Leiste und dahinter die Image Lightbox.

"use client";

import { ProductGallery, type ProductGalleryImage } from "@/components/ui/product-gallery";

const images: ProductGalleryImage[] = [
  { src: "/products/chair-front.jpg", alt: "Loungesessel aus Eiche, von vorn", width: 1200, height: 900 },
  { src: "/products/chair-side.jpg", alt: "Loungesessel aus Eiche, von der Seite", width: 1200, height: 900 },
  { src: "/products/chair-detail.jpg", alt: "Detail der Wollpolsterung", width: 1200, height: 900 },
];

export function ProductPhotos() {
  return <ProductGallery images={images} fit="contain" zoom="lens" bleedOnMobile lightboxProps={{ download: true }} />;
}

Mit der Maus vergrößert zoom="hover" (der Standard) das Foto an Ort und Stelle und verschiebt es mit dem Cursor, zoom="lens" zeigt stattdessen eine runde Lupe. In beiden Fällen geht der Zoom nie über die doppelte natürliche Breite des Fotos hinaus, damit kleine Dateien nicht zu Matsch werden. fit="contain" zeigt Produktfotos im Light Mode vollständig, mit Rand auf weißem Grund. Die Thumbnails sitzen in einer Leiste neben der Bühne, sobald die Galerie mindestens 512px breit ist (eine Container Query, also klappt das auch in einer schmalen Spalte), und das letzte sichtbare zeigt „+N“.

Am Smartphone gibt es keinen Hover-Zoom und keine Thumbnail-Leiste: Über die Bühne wischt du von Foto zu Foto, ein Zähler „3 / 12“ oder Punkte zeigen die Position, und ein Tipp öffnet den Vollbild-Viewer, in dem Pinch-Zoom und Swipe to Close wie oben funktionieren. Das ist die ehrliche Antwort auf die Suche nach „React Bildergalerie Zoom“: Hover-Zoom ist für die Maus, Pinch für Finger, und eine Komponente sollte nicht so tun, als wäre das dasselbe.

Was sind die typischen Fehler bei einer React Lightbox?

Drei weitere tauchen auf, sobald echte Fotos die Demodaten ersetzen. Fehlende Abmessungen haben wir oben schon behandelt; die Lösung ist, Breite und Höhe schon beim Hochladen des Fotos zu speichern.

• Dateien in voller Größe im Raster. Gib pro Bild ein thumbnail mit oder ein srcSet und sizes.
• Wisch nach unten auf einem gezoomten Foto. Schalte in deinem eigenen Viewer die Schließen-Geste ab, solange der Zoomfaktor über 1 liegt, sonst schließt ein Verschieben den Viewer.
• Eine kaputte Datei, die das Blättern blockiert. Fehlt ein Bild, zeigt der Viewer von Wingo UI ein Icon in der Kachel und im Vollbild, und Weiterwischen funktioniert trotzdem. Teste diesen Fall mit deinen eigenen Daten.

Wenn Nutzer diese Fotos hochladen, zeigt der Guide zum React Image Cropper, wie du das Seitenverhältnis korrigierst, bevor sie in der Galerie landen.

Wie baue ich sie in mein Projekt ein?

Führ npx wingo-ui@latest add image-lightbox für Viewer und Raster aus oder npx wingo-ui@latest add product-gallery für die Galerie der Detailseite (sie bringt die Lightbox mit). Die CLI kopiert die Komponente nach components/ui, ergänzt das Carousel, die Hooks und Helfer, die sie importiert, und installiert ihre npm-Pakete. Beide sind Pro-Komponenten (Preise). Weitere Deep Dives zu einzelnen Komponenten findest du in der Kategorie Komponenten-Guides, und der Guide zu React Formular-Komponenten wendet dieselben Regeln für Touch, Tastatur und Screenreader auf jedes Formularelement an.

Häufige Fragen

Welche React Lightbox Library ist die beste?

Als fertiges Paket sind Yet Another React Lightbox (MIT, React 16.8 bis 19, Zoom und Thumbnails als Plugins) und PhotoSwipe (MIT, frameworkunabhängig, mit eigenem React-Guide) die üblichen Kandidaten. Das ursprüngliche Paket react-image-lightbox wurde im Januar 2023 archiviert. Die Image Lightbox von Wingo UI ist eine Pro-Komponente, die du als Quellcode in dein Projekt kopierst.

Gibt es eine shadcn Lightbox?

Nein. shadcn/ui liefert ein Carousel auf Basis von Embla und einen Dialog, aber Stand Oktober 2026 keine Lightbox und keinen Bildbetrachter. Die Image Lightbox von Wingo UI verbindet genau diese beiden Ideen (ein Embla-Carousel in einem Radix-Dialog), und du installierst sie mit npx wingo-ui@latest add image-lightbox.

Wie schließe ich eine Lightbox am Smartphone mit einem Wisch nach unten?

Verfolg die vertikale Ziehbewegung auf dem Foto, verkleinere das Foto und blende den Hintergrund aus, während es dem Finger folgt, und schließ den Viewer, sobald die Bewegung einen festgelegten Anteil des Bildschirms überschreitet oder ein schneller Wisch kommt. Der Viewer von Wingo UI schließt ab einem Viertel der Bildschirmhöhe oder bei einem Wisch schneller als 400px pro Sekunde und federt sonst zurück.

Warum springt meine Lightbox, wenn das Bild lädt?

Der Viewer kennt die Form des Fotos erst, wenn die Datei da ist. Gib für jedes Bild width und height mit, damit der Rahmen sofort sein endgültiges Seitenverhältnis bekommt, und eine kleine Thumbnail-Datei als Platzhalter, bis die volle Datei geladen ist.

Ist die Image Lightbox von Wingo UI kostenlos?

Nein. Die Image Lightbox, die Product Gallery und das Carousel, auf dem beide aufbauen, sind Pro-Komponenten. Der Button und der Spinner, die sie nutzen, sind kostenlos.