Parvus

An accessible, open-source image lightbox with no dependencies.

Image viewer
deoostfrees/Parvusparvus

README

Parvus


Overlays are not recommended to use, but if you need one, you can consider using Parvus. Parvus is an open-source image lightbox that aims to be accessible and has no dependencies.

Screenshot of Parvus. It shows the first picture of a gallery.

Open in CodePen

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 to your HTML file. Your HTML code should look like this:

  1. ```html
  2. <!DOCTYPE html>
  3. <html lang="en">
  4. <head>
  5.   <meta charset="UTF-8">
  6.   <meta name="viewport" content="width=device-width, initial-scale=1">
  7.   <title>Page title</title>
  9.   !-- CSS -->
  10.   <link href="path/to/parvus.min.css" rel="stylesheet">
  11. </head>
  12. <body>
  13.   !-- HTML content -->
  15.   !-- JS -->
  16.   <script src="path/to/parvus.min.js"></script>
  17. </body>
  18. </html>
  19. ```

Package Managers


You can also install Parvus using npm or yarn, like any other dependency:

  1. ```
  2. npm install parvus
  3. ```

or

  1. ```
  2. yarn add parvus
  3. ```

After installation, you can import Parvus into your JavaScript codebase:

  1. ```js
  2. import Parvus from 'parvus'
  3. ```

Make sure to include the corresponding SCSS or CSS file.

Usage


The standard way to use Parvus is by linking a thumbnail image with the class lightbox to a larger image.

  1. ```html
  2. <a href="path/to/image.jpg" class="lightbox">
  3.   <img src="path/to/thumbnail.jpg" alt="">
  4. </a>
  5. ```

Initialize the script by running:

  1. ```js
  2. const prvs = new Parvus()
  3. ```

Captions


If you want to show a caption under the image, you can add a data-caption attribute.

  1. ```html
  2. <a href="path/to/image.jpg" class="lightbox" data-caption="I'm a caption">
  3.   <img src="path/to/thumbnail.jpg" alt="">
  4. </a>
  5. ```

Alternatively, you can set the option captionsSelector to select the captions from the innerHTML of an element.

  1. ```html
  2. <a href="path/to/image.jpg" class="lightbox">
  3.   <figure class="figure">
  4.     <img src="path/to/thumbnail.jpg" alt="">
  6.     <figcaption class="figure__caption">
  7.       <p>I'm a caption</p>
  8.     </figcaption>
  9.   </figure>
  10. </a>
  11. ```

  1. ```js
  2. const prvs = new Parvus({
  3.   captionsSelector: '.figure__caption',
  4. })
  5. ```

Gallery


If you have a group of related images that you would like to combine into a set, you can add a data-group attribute:

  1. ```html
  2. <a href="path/to/image.jpg" class="lightbox" data-group="Berlin">
  3.   <img src="path/to/thumbnail.jpg" alt="">
  4. </a>
  6. <a href="path/to/image_2.jpg" class="lightbox" data-group="Berlin">
  7.   <img src="path/to/thumbnail_2.jpg" alt="">
  8. </a>
  10. //...
  12. <a href="path/to/image_8.jpg" class="lightbox" data-group="Kassel">
  13.   <img src="path/to/thumbnail_8.jpg" alt="">
  14. </a>
  15. ```

Alternatively, you can set the option gallerySelector to combine all images with a specific class within a selector into a group.

  1. ```html
  2. <div class="gallery">
  3.   <a href="path/to/image.jpg" class="lightbox">
  4.     <img src="path/to/thumbnail.jpg" alt="">
  5.   </a>
  7.   <a href="path/to/image_2.jpg" class="lightbox">
  8.     <img src="path/to/thumbnail_2.jpg" alt="">
  9.   </a>
  11.   // ...
  12. </div>
  13. ```

  1. ```js
  2. const prvs = new Parvus({
  3.   gallerySelector: '.gallery',
  4. })
  5. ```

Responsive Images


You can specify different image sources and sizes using the data-srcset and data-sizes attribute.

  1. ```html
  2. <a href="path/to/image.jpg" class="lightbox"
  4. data-srcset="path/to/small.jpg 700w,
  5.              path/to/medium.jpg 1000w,
  6.              path/to/large.jpg 1200w"
  8. data-sizes="(max-width: 75em) 100vw,
  9.             75em"
  10. >
  11.   <img src="path/to/thumbnail.jpg" alt="">
  12. </a>
  13. ```

Localization


If you need localization, you can import the language module and set it as an option.

  1. ```js
  2. import de from 'parvus/src/l10n/de'

  4. const prvs = new Parvus({
  5.   l10n: de
  6. })
  7. ```

Options


You can pass an object with custom options as an argument when initializing Parvus.

  1. ```js
  2. const prvs = new Parvus({
  3.   // Clicking outside closes Parvus
  4.   docClose: false
  5. })
  6. ```

The following options are available:

  1. ```js
  2. {
  3.   // Selector for elements that trigger Parvus
  4.   selector: '.lightbox',

  6.   // Selector for a group of elements that should be combined as a gallery. Overrides the `data-group` attribute.
  7.   gallerySelector: null,

  9.   // Display captions if available
  10.   captions: true,

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

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

  18.   // Clicking outside closes Parvus
  19.   docClose: true,

  21.   // Closing Parvus by swiping up/down
  22.   swipeClose: true,

  24.   // Accepting mouse events like touch events (click and drag to change slides)
  25.   simulateTouch: true,

  27.   // Touch dragging threshold (in pixels)
  28.   threshold: 100,

  30.   // Setting focus back to the trigger element after closing Parvus
  31.   backFocus: true,

  33.   // Browser scrollbar visibility
  34.   hideScrollbar: true,

  36.   // Duration of transition effects in milliseconds (ms)
  37.   transitionDuration: 300,

  39.   // Timing function of the transition effects
  40.   transitionTimingFunction: 'cubic-bezier(0.2, 0, 0.2, 1)',

  42.   // Icons
  43.   lightboxIndicatorIcon: '',
  44.   previousButtonIcon: '',
  45.   nextButtonIcon: '',
  46.   closeButtonIcon: '',

  48.   // Localization of strings
  49.   l10n: en
  50. }
  51. ```

API


Parvus provides the following API functions:

FunctionDescription
------
`open(element)`Open
`close()`Close
`previous()`Show
`next()`Show
`select(index)`Select
`add(element)`Add
`remove(element)`Remove
`destroy()`Destroy
`isOpen()`Check
`currentIndex()`Get

Events


You can bind and unbind events using the .on() and .off() methods.

  1. ```js
  2. const prvs = new Parvus()

  4. const listener = function listener () {
  5.   console.log('eventName happened')
  6. }

  8. // bind event listener
  9. prvs.on(eventName, listener)

  11. // unbind event listener
  12. prvs.off(eventName, listener)
  13. ```

The following events are available:

eventNameDescription
------
`open`Triggered
`select`Triggered
`close`Triggered
`destroy`Triggered

Except for the destroy event, you can access the current source element using the event.detail.source property.

  1. ```js
  2. prvs.on('open', function (event) {
  3.   console.log(event.detail.source);
  4. })
  5. ```

Browser Support


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

- Chrome
- Edge
- Firefox
- Safari