Zoom Plugin

Zoom plugin adds image zoom feature to the lightbox.

The plugin supports the following input devices and gestures:

Input deviceZoomPan
Touchscreen
  • pinch-to-zoom
  • double-tap
  • swipe
Touchpad
  • pinch-to-zoom
  • double-tap
  • double-click
  • scroll (swipe with two fingers)
  • click-and-drag
Keyboard
  • +, -
  • ⌘ + =, ⌘ + -, ⌘ + 0
  • ⊞ + =, ⊞ + -, ⊞ + 0
  • ←, →, ↑, ↓
Mouse
  • zoom (Ctrl + mouse wheel)
  • double-click
  • scroll (mouse wheel)
  • click-and-drag

Requirements

The plugin currently supports only image slides. Custom render functions are also supported as long as the slide provides width and height attributes.

If you need support for custom slide types, please open a discussion and provide a specific use case.

Documentation

Zoom plugin adds the following Lightbox properties.

PropertyTypeDescription
zoom

{
  ref?: React.ForwardedRef​<ZoomRef>;
  maxZoomPixelRatio?: number;
  zoomInMultiplier?: number;
  doubleTapDelay?: number;
  doubleClickDelay?: number;
  doubleClickMaxStops?: number;
  keyboardMoveDistance?: number;
  wheelZoomDistanceFactor?: number;
  pinchZoomDistanceFactor?: number;
  scrollToZoom?: boolean;
}

Zoom plugin settings:

  • ref - Zoom plugin ref. See Zoom Ref for details.
  • maxZoomPixelRatio - ratio of image pixels to physical pixels at maximum zoom level
  • zoomInMultiplier - zoom-in multiplier
  • doubleTapDelay - double-tap maximum time delay (deprecated)
  • doubleClickDelay - double-click maximum time delay (deprecated)
  • doubleClickMaxStops - maximum number of zoom-in stops via double-click or double-tap
  • keyboardMoveDistance - keyboard move distance
  • wheelZoomDistanceFactor - wheel zoom distance factor
  • pinchZoomDistanceFactor - pinch zoom distance factor
  • scrollToZoom - if true, enables image zoom via scroll gestures for mouse and trackpad users

Default: { maxZoomPixelRatio: 1, zoomInMultiplier: 2, doubleTapDelay: 300, doubleClickDelay: 500, doubleClickMaxStops: 2, keyboardMoveDistance: 50, wheelZoomDistanceFactor: 100, pinchZoomDistanceFactor: 100, scrollToZoom: false }

animation

{
  zoom?: number;
}

Zoom animation duration.

Default: 500

render

{
  slide?: ({..., zoom, maxZoom}: {..., zoom: number; maxZoom: number }) => React.ReactNode;
  buttonZoom?: (props: ZoomRef) => React.ReactNode;
  iconZoomIn?: () => React.ReactNode;
  iconZoomOut?: () => React.ReactNode;
}

Custom render functions:

  • slide - Zoom plugin adds zoom and maxZoom props to the slide render function
  • buttonZoom - render custom Zoom In / Zoom Out control
  • iconZoomIn - render custom Zoom In icon
  • iconZoomOut - render custom Zoom Out icon
on

{
  zoom?: ({ zoom }: { zoom: number }) => void;
}

Callbacks:

  • zoom - a callback called when zoom level changes

Zoom Ref

Zoom plugin provides a ref object to control the plugin features externally.

// Zoom ref usage example

const zoomRef = React.useRef(null);

// ...

return (
  <>
    <Lightbox
      slides={slides}
      plugins={[Inline, Zoom]}
      zoom={{ ref: zoomRef }}
      inline={{
        style: { width: "100%", maxWidth: "900px", aspectRatio: "3 / 2" },
      }}
    />

    <button type="button" onClick={() => zoomRef.current?.zoomIn()}>
      Zoom In
    </button>

    <button type="button" onClick={() => zoomRef.current?.zoomOut()}>
      Zoom Out
    </button>
  </>
);
PropertyTypeDescription
zoomnumberCurrent zoom level.
maxZoomnumberMaximum zoom level.
offsetXnumberHorizontal offset.
offsetYnumberVertical offset.
disabledboolean
If true, zoom is unavailable for the current slide.
zoomIn() => void
Increase zoom level using zoomInMultiplier.
zoomOut() => void
Decrease zoom level using zoomInMultiplier.
changeZoom(targetZoom: number, rapid?: boolean, dx?: number, dy?: number) => void

Change zoom level.

  • targetZoom - target zoom value
  • rapid - if true, change zoom level without animation effect
  • dx - horizontal offset
  • dy - vertical offset

Example

import Lightbox from "yet-another-react-lightbox";
import Zoom from "yet-another-react-lightbox/plugins/zoom";
import "yet-another-react-lightbox/styles.css";

// ...

return (
  <Lightbox
    plugins={[Zoom]}
    // ...
  />
);

Live Demo

You can adjust the live demo settings below.

Sandbox

Edit on StackBlitz