Parvus

Overlays suck, but if you need one, consider using Parvus. Parvus is an open source, dependency free image lightbox with the goal of being accessible.

Open in CodePen

Table of Contents

Installation
- Download
- Package Managers
Usage
- Captions
- Gallery
- Responsive Images
- Localization
Options
API
Events
Browser Support

Installation

Download

CSS:
- dist/css/parvus.min.css (minified) or
- dist/css/parvus.css (un-minified)
JavaScript:
- dist/js/parvus.min.js (minified) or
- dist/js/parvus.js (un-minified)

Link the .css and .js files in your HTML:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Page title</title>

  <!-- CSS -->
  <link href="path/to/parvus.min.css" rel="stylesheet">
</head>
<body>
  <!-- HTML content -->

  <!-- JS -->
  <script src="path/to/parvus.min.js"></script>
</body>
</html>

Package Managers

You can also install Parvus using npm or yarn:

npm install parvus

or

yarn add parvus

After installation, import Parvus into your JavaScript codebase:

import Parvus from 'parvus'

Be sure to include the corresponding SCSS or CSS file.

Usage

Link a thumbnail image with the class lightbox to a larger image:

<a href="path/to/image.jpg" class="lightbox">
  <img src="path/to/thumbnail.jpg" alt="">
</a>

Initialize the script:

const prvs = new Parvus()

Captions

To show a caption under the image, add a data-caption attribute:

<a href="path/to/image.jpg" class="lightbox" data-caption="I'm a caption">
  <img src="path/to/thumbnail.jpg" alt="">
</a>

Alternatively, set the option captionsSelector to select captions from an element's innerHTML:

<a href="path/to/image.jpg" class="lightbox">
  <figure class="figure">
    <img src="path/to/thumbnail.jpg" alt="">

    <figcaption class="figure__caption">
      <p>I'm a caption</p>
    </figcaption>
  </figure>
</a>

const prvs = new Parvus({
  captionsSelector: '.figure__caption',
})

Gallery

To group related images into a set, add a data-group attribute:

<a href="path/to/image.jpg" class="lightbox" data-group="Berlin">
  <img src="path/to/thumbnail.jpg" alt="">
</a>

<a href="path/to/image_2.jpg" class="lightbox" data-group="Berlin">
  <img src="path/to/thumbnail_2.jpg" alt="">
</a>

//...

<a href="path/to/image_8.jpg" class="lightbox" data-group="Kassel">
  <img src="path/to/thumbnail_8.jpg" alt="">
</a>

Alternatively, set the option gallerySelector to group all images with a specific class within a selector:

<div class="gallery">
  <a href="path/to/image.jpg" class="lightbox">
    <img src="path/to/thumbnail.jpg" alt="">
  </a>

  <a href="path/to/image_2.jpg" class="lightbox">
    <img src="path/to/thumbnail_2.jpg" alt="">
  </a>

  // ...
</div>

const prvs = new Parvus({
  gallerySelector: '.gallery',
})

Responsive Images

Specify different image sources and sizes using the data-srcset and data-sizes attributes:

<a href="path/to/image.jpg" class="lightbox"

data-srcset="path/to/small.jpg 700w,
             path/to/medium.jpg 1000w,
             path/to/large.jpg 1200w"

data-sizes="(max-width: 75em) 100vw,
            75em"
>
  <img src="path/to/thumbnail.jpg" alt="">
</a>

Localization

Import the language module and set it as an option for localization:

import de from 'parvus/src/l10n/de'

const prvs = new Parvus({
  l10n: de
})

Options

Customize Parvus by passing an options object when initializing:

const prvs = new Parvus({
  // Clicking outside does not close Parvus
  docClose: false
})

Available options include:

{
  // Selector for elements that trigger Parvus
  selector: '.lightbox',

  // Selector for a group of elements combined as a gallery, overrides the `data-group` attribute.
  gallerySelector: null,

  // Display zoom indicator
  zoomIndicator: true,

  // Display captions if available
  captions: true,

  // Selector for the element where the caption is displayed; use "self" for the `a` tag itself.
  captionsSelector: 'self',

  // Attribute to get the caption from
  captionsAttribute: 'data-caption',

  // Clicking outside closes Parvus
  docClose: true,

  // Close Parvus by swiping up/down
  swipeClose: true,

  // Accept mouse events like touch events (click and drag to change slides)
  simulateTouch: true,

  // Touch dragging threshold in pixels
  threshold: 100,

  // Hide browser scrollbar
  hideScrollbar: true,

  // 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
}

API

Parvus provides the following API functions:

Function	Description
`open(element)`	Open the specified `element` (DOM element)
`close()`	Close Parvus
`previous()`	Show the previous image
`next()`	Show the next image
`select(index)`	Select a slide with the specified `index` (integer)
`add(element)`	Add the specified `element` (DOM element)
`remove(element)`	Remove the specified `element` (DOM element)
`destroy()`	Destroy Parvus
`isOpen()`	Check if Parvus is currently open
`currentIndex()`	Get the index of the currently displayed slide

Events

Bind and unbind events using the .on() and .off() methods:

const prvs = new Parvus()

const listener = () => {
  console.log('eventName happened')
}

// Bind event listener
prvs.on(eventName, listener)

// Unbind event listener
prvs.off(eventName, listener)

Available events:

eventName	Description
`open`	Triggered after Parvus has opened
`select`	Triggered when a slide is selected
`close`	Triggered after Parvus has closed
`destroy`	Triggered after Parvus has destroyed

Browser Support

Parvus is supported on the latest versions of the following browsers:

Chrome
Edge
Firefox
Safari