photoswiper

v3.0.4

Published

2 years ago

A plugin for easy and accessible PhotoSwipe initialization

Downloads

0High
0Medium
0Low

sh0ji

photoswipe accessibility a11y

Photoswiper

An plugin for easy and accessible PhotoSwipe initialization.

Usage

Photoswiper comes with three versions: a Node.js version, an ES module version, and a standalone version that can be used in the browser. All versions will automatically set up event listeners to open the PhotoSwipe instance on click.

Node

Import Photoswiper
Instantiate Photoswiper with a gallery element

const Photoswiper = require('photoswiper');

const myGallery = new Photoswiper(document.getElementById('my-gallery'));

ES Module

Add the script to your document
Import it and instantiate Photoswiper

<html lang="en">
  <head>
    <!-- ...other head stuff... -->
    <script src="scripts/photoswiper.esm.js" type="module"></script>
    <script src="scripts/main.js" type="module"></script>
  </head>
  <!-- ...body... -->
</html>

Main.js:

import Photoswiper from './scripts/photoswiper.esm.js';

const myGallery = new Photoswiper(document.getElementById('my-gallery'));

Browser

Add the script to your document
Instantiate Photoswiper with a gallery element

<html lang="en">
  <head>
    <!-- ...other head stuff... -->
    <script src="scripts/photoswiper.umd.js" defer></script>
    <script src="scripts/main.js" defer></script>
  </head>
  <!-- ...body... -->
</html>

Main.js:

"use strict"

var myGallery = new Photoswiper(document.getElementById('my-gallery'));

API

A few helpful hooks are available on the Photoswiper instance.

#disable()

Disable the event listeners so that the PhotoSwipe instance isn't triggered on click.

#enable()

Enable the event listeners so that the PhotoSwipe instance is triggered on click. Note that this is automatically set during instantiation. You only need to call it if you've explicitly disabled the instance.

#toggle()

Switch between enabled/disabled.

#open(index: number, triggerEl: HTMLElement, fromUrl: boolean = false)

Open the PhotoSwipe instance. This is what is called on click.

For example, you can use this to open the PhotoSwipe instance when clicking another element:

// this assumes a button with aria-controls:
// <button id="some-button" aria-controls="id-of-pswp-item">...</button>
// and a gallery item with a data-pid corresponding to its index in the gallery:
// <figure id="id-of-pswp-item" data-pid="2">...</figure>

const triggerBtn = document.getElementById('some-button');
triggerBtn.onclick = function openRelated() {
  const related = document.getElementById(this.getAttribute('aria-controls'));
  const i = parseInt(related.getAttribute('data-pid'), 10);
  myGallery.open(i, this);
}

Options

Photoswiper provides a few extra options in addition to all the PhotoSwipe options.

| Option | Type | Default | | ---- | ---- | ---- | | bemRoot | string | undefined | | onInit | function | noop | | onOpen | function | noop | | PhotoSwipeUI | function | The default PhotoSwipe UI. | | selectors | object | See the Selectors documentation. |

bemRoot

Use this to customize your selectors according to BEM BEM conventions. For instance, passing myImages would cause the figure element selector to become .myImages__figure instead of .pswp-gallery__figure.

onInit(figures: NodeList)

This is called at the end of Photoswiper construction, but before the PhotoSwipe gallery has been opened. Note that PhotoSwipe has an onInit hook that is called when the PhotoSwipe instance opens.

const myGallery = new Photoswiper(galleryEl, {
  onInit(figures) {
    // do something with the list of figures, such as setting data-pid indices
    figures.forEach((figure, i) => {
      figure.setAttribute('data-pid', i);
    });
  },
});

onOpen(pswp: PhotoSwipe instance)

This is called when PhotoSwipe opens. It corresponds to PhotoSwipe's own onInit hook.

const myGallery = new Photoswiper(galleryEl, {
  onOpen(pswp) {
    // do something with the photoswipe instance
    console.log(pswp);
  },
});

photoswipeUI

Specify your PhotoSwipe ui function here. Defaults to the default PhotoSwipe UI.

Selectors

NOTE: this was renamed from "Structure" in v3.0

Photoswiper defaults to semantic element selectors, but all selectors can be explicitly overriden. Optionally use BEM by supplying a bemRoot class name in the options (e.g. { bemRoot: 'pswp-gallery' }). Elements include:

| Option Name | Default | BEM Output | Description | | ---- | ---- | ---- | ---- | | GALLERY | figure | .${bemRoot} | The root gallery element. | | TITLE | figcaption | .${bemRoot}__title | The title of the whole gallery. There can only be one of these per gallery, and it must be a direct child of the GALLERY. | | FIGURE | figure | .${bemRoot}__figure | The figure container | | LINK | a | .${bemRoot}__link | The anchor element that contains the full resolution image. | | THUMB | img | .${bemRoot}__thumbnail | The img thumbnail. | | CAPTION | figcaption | .${bemRoot}__caption | Captions for each image. | | PSWP | .pswp | N/A | The PhotoSwipe element. |

Example Markup

This example assumes a bemRoot of "pswp-gallery":

const myGallery = new Photoswiper(galleryEl, { bemRoot: 'pswp-gallery' });

<figure class="pswp-gallery">
  <figcaption class="pswp-gallery__title">Kittens</figcaption>
  <figure class="pswp-gallery__figure">
    <a class="pswp-gallery__link" href="http://placekitten.com/2000/1500">
      <img class="pswp-gallery__thumbnail" src="http://placekitten.com/200/150" alt="An orange and white kitten looks on from behind a doorframe." />
    </a>
    <figcaption class="pswp-gallery__caption">Kittens are tiny cats.</figcaption>
  </figure>
</figure>
<!-- ...other content... -->

<!-- http://photoswipe.com/documentation/getting-started.html#init-add-pswp-to-dom -->
<div class="pswp">...</div>