simplelightbox.com
Home / Guides / Touch and zoom

Touch, swipe and zoom

Tune gestures, keyboard control and page scrolling

Gestures out of the box

SimpleLightbox is touch-friendly without configuration. Swipe sideways to change the photo, swipe up or down to close it, pinch or double-tap to zoom in. On desktop the mouse wheel and a double click zoom as well.

OptionDefaultControls
swipeTolerance50Pixels a finger must travel before the next or previous photo is shown
swipeClosetrueSwipe up or down to close the lightbox
doubleTapZoom2Zoom level after a double tap
maxZoom10Upper limit for pinch zoom
scrollZoomtrueZoom with the mouse wheel
scrollZoomFactor0.5How much one wheel step zooms

All of these options belong to the lightbox instance they are passed to. One page can therefore hold a gallery tuned for detailed product shots next to another one that keeps the defaults, each created with its own selector.

Keyboard and focus

enableKeyboard lets visitors move with the arrow keys and close the viewer with ESC. focus moves focus into the lightbox when it opens, so keyboard users can tab through its buttons instead of the page behind it. Both are on by default and there is rarely a reason to disable them.

The page behind

While the lightbox is open, disableScroll stops the page from scrolling. Hiding the scrollbar would normally make the layout jump sideways; the lightbox compensates with padding on the body. Fixed elements such as a sticky header need the same padding — give them the class set in fixedClass (sl-fixed by default).

htmlClass adds a class to the <html> element while the lightbox is open (has-lightbox by default), for any styling of your own — for example pausing a background video.

<header class="site-header sl-fixed">…</header>

The defaults suit photo galleries. Two common cases need a small adjustment:

  • Product photos and detailed images — allow a stronger double-tap zoom and a finer mouse-wheel step.
  • Screenshots in documentation — turn off scrollZoom, so scrolling with a trackpad does not zoom by accident.
// detailed photos
new SimpleLightbox('.product-gallery a', {
    doubleTapZoom: 3,
    maxZoom: 6,
    scrollZoomFactor: 0.3,
    swipeTolerance: 30
});

// documentation screenshots
new SimpleLightbox('.screenshots a', { scrollZoom: false });

Whatever you choose, test on a real phone. Desktop browsers can emulate touch events, but not the feel of a swipe under a thumb, and a tolerance that seems right with a mouse can turn out too sensitive on a small screen.

The two photos below use the first configuration. Double-tap or scroll on an open image to try it:

Snow-covered summit in the clouds Weir on a river in a park

More guides

Or go back to the full list of options.