Accessible Mobile-friendly Image Lightbox Library – Parvus.js

An accessible, touch-enabled, user-friendly image lightbox component written in plain JavaScript.

Features:

• Zoom in/out images on hover.
• Image loading indicator.
• Scroll or swipe to close just like Medium.com’s lightbox.
• Supports pinch zoom gestures.
• Based  on the native <dialog> element.
• Useful API methods and event handlers.
• Image counter.

How to use it:

1. You can also install & download the package with NPM.

# NPM
$ npm i react-spinners-css

2. Add references to Parvus JavaScript & CSS files.

<link rel="stylesheet" href="dist/css/parvus.min.css" />
<script src="dist/js/parvus.min.js"></script>

3. Create a new instance of the Parvus.js and pass the options as follows:

const prvs = new parvus({
  // All elements with this class triggers Parvus
  selector: '.lightbox',
  // All `selector` in this `gallerySelector` are combined as a gallery. Overwrites the `data-group` attribute
  gallerySelector: null,
  // Display zoom indicator
  zoomIndicator: true,
  // Display captions, if available
  captions: true,
  // Set the element where the caption is. Set it to "self" for the `a` tag itself
  captionsSelector: 'self',
  // Get the caption from given attribute
  captionsAttribute: 'data-caption',
  // Click outside to close Parvus
  docClose: true,
  // Swipe up/ down to close Parvus
  swipeClose: true,
  // Accepting mouse events like touch events (click and drag to change slides)
  simulateTouch: true,
  // Touch dragging threshold (in px)
  threshold: 100,
  // Browser scrollbar visibility
  hideScrollbar: true,
  // Specifies the speed curve of the transition effects
  transitionTimingFunction: 'cubic-bezier(0.2, 0, 0.2, 1)',
  // Icons
  lightboxIndicatorIcon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M8 3H5a2 2 0 00-2 2v3m18 0V5a2 2 0 00-2-2h-3m0 18h3a2 2 0 002-2v-3M3 16v3a2 2 0 002 2h3"/></svg>',
  previousButtonIcon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path stroke="none" d="M0 0h24v24H0z"/><polyline points="15 6 9 12 15 18" /></svg>',
  nextButtonIcon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path stroke="none" d="M0 0h24v24H0z"/><polyline points="9 6 15 12 9 18" /></svg>',
  closeButtonIcon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M18 6L6 18M6 6l12 12"/></svg>',
  // Localization of strings
  l10n: en,
});

4. Apply the image lightbox to an image element. That’s it.

<a href="full.jpg" class="image-lightbox" data-caption="Caption Here">
  <img src="thumb.jpg" alt="Image Alt" />
</a>

imageSelector = document.querySelector('.image-lightbox');
prvs.add(imageSelector);

6. Create a gallery lightbox by grouping your images using the ‘data-group’ attribute or ‘gallerySelector’ option.

<a href="1.jpg" class="lightbox" data-group="Berlin">
  <img src="1.jpg" alt="">
</a>
<a href="2.jpg" class="lightbox" data-group="Berlin">
  <img src="2.jpg" alt="">
</a>
<a href="3.jpg" class="lightbox" data-group="Kassel">
  <img src="3.jpg" alt="">
</a>

7. More API methods.

// add an image element
prvs.add(element);
// remove an image element
prvs.remove(element);
// open the lightbox
prvs.open(el);
// close the lightbox
prvs.close();
// destroy the instance
prvs.destroy(destroy);
// check if is open
prvs.isOpen();
// get the current index
prvs.currentIndex();
// go to the prev image
prvs.previous();
// go to the next image
prvs.next();
// select a slide
prvs.select(index);

6. Bind/unbind event listeners.

// prvs.on(eventName, listener)
// prvs.off(eventName, listener)
prvs.on('open', listener);
prvs.on('close', listener);
prvs.on('select', listener);
prvs.on('destroy', listener);

Changelog:

v3.0.0 (03/16/2024)

• Added Pinch zoom gestures
• Added Option to make the zoom indicator optional
• Use the native HTML dialog element
• Use the View Transitions API for the zoom in/ out animation
• Use pointer events instead of mouse and touch events

v2.6.0 (06/06/2024)

• Bugfix
• Run change event listener for reducedMotionCheck only when the lightbox is open

v2.5.3 (04/27/2024)

• Bugfix

v2.5.1 (04/10/2024)

• Bugfix

v2.5.0 (04/08/2024)

• Added option to load an empty lightbox (even if there are no elements)
• Added a fallback to the default language
• Added Dutch translation
• Rename some CSS custom properties
• Removed Slide animation when first/ last slide is visible

v2.4.0 (07/21/2023)

• Added Option to hide the browser scrollbar
• Added an internal function to create and dispatch a new event.
• Disabled buttons are no longer visually hidden.
• Focus is no longer moved automatically.
• CSS styles are now moved from SVG to the actual elements.
• Updated the development dependencies to the latest versions.
• Removed Custom typography styles.
• Fixed Load the srcset before the src, add sizes attribute

v2.3.3 (05/31/2023)

• Animate current image and set focus back to the correct element in the default behavior of the backFocus option
• Set focus back to the correct element in the default behavior of the backFocus option.
• Fixed The navigation buttons’ visibility.

v2.3.0 (05/28/2023)

• Added Necessary outputs for screen reader support.
• Added CSS custom properties for captions and image loading error messages.
• Replaced the custom copyObject() function with the built-in structuredClone() method for improved performance and reliability.
• Refactored code and comments to improve readability and optimize performance.
• Updated the development dependencies to the latest versions.
• Removed The option for supported image file types as it is no longer necessary.
• Removed The scrollClose option.
• Fixed Non standard URLs can break Parvus.

v2.2.0 (11/30/2022)

• Fix Safari background scrolling
• Use arrow functions
• Use CSS logical properties
• Update dev dependencies

v2.1.0 (07/07/2022)

• Add option to accept mouse events like touch events (click and drag to change slides)

v2.0.4 (01/21/2022)

• Add aria-labelledby for slides with captions
• Improvements
• Clean up

v2.0.3 (01/19/2022)

• Fix issue when loading an image for the first time
• Improvements

v2.0.2 (01/19/2022)

• Use box-sizing: border-box
• Fix issue with duplicate slides

v2.0.1 (01/18/2022)

• Fix issue with slides without caption
• Fix new “reset groups” disaster

v2.0.0 (01/18/2022)

• Update dev dependencies
• Remove own focus style
• Add more options for captions
• Breaking change Refactor localization
• Add toolbar container for future functions
• Fix: Add function to calculate image

v1.4.1 (09/30/2021)

• Update dev dependencies