simonselg/photoswippy

A no-(extra)-dependency PhotoSwipe friendly wrapper

PhotoSwippy

PhotoSwipe is an awesome modular, lightweight and fast lightbox. Unfortunately its implementation can be a bit cumbersome, having to write a lot of code. There are some helpers, such as jquery.photoswipe and photoswiper, but something simpler, but still configurable, was needed and so PhotoSwippy was born.

Installation

npm install --save photoswippy

yarn add photoswippy

bower install --save photoswippy

Usage

PhotoSwippy is just a wrapper for PhotoSwipe. This means you still have to import/include the PhotoSwipe and PhotoSwipeUI libraries (and the rest of the relevant assets such as CSS and icons). PhotoSwippy expects that the PhotoSwipe template element has the pswp class and it's already on the DOM.

Module

import PhotoSwipe from 'photoswipe'
import PhotoSwipeUIDefault from 'photoswipe/dist/photoswipe-ui-default'
import PhotoSwippy from 'photoswippy'

PhotoSwippy.init(
  PhotoSwipe,
  PhotoSwipeUIDefault,
  optionsObject = {}
)

Browser

<script src="..../photoswipe.js"></script>
<script src="..../photoswipe-ui-default.min.js"></script>
<script src="..../photoswippy.js"></script>
<script type="text/javascript">
  photoswippy.init(PhotoSwipe, PhotoSwipeUI_Default, options)
</script>

If both PhotoSwipe and PhotoSwipeUI_Default are on the global scope, the first parameters of .init can be undefined.

How it works

Each element with a data-pswp attribute will become a photoswipe gallery. Its value is optional and defines the gallery ID. That's it.

The default itemSelector is a and PhotoSwippy searches it for:

• URL of image to be opened (href or data-pswp-src)
• Size of image to be opened (data-pswp-width AND data-pswp-height OR data-pswp-size="WIDTHxHEIGHT")
• Caption (data-pswp-caption or the options.captionSelector HTML or the thumbnail's alt attribute value)

Obs: PhotoSwipe requires to previously know the size of the image to be opened. However, PhotoSwippy allows you to ommit it if there's really no way to know the size values.

Example:

<!-- Default id is: 'gallery-{0..numberOfGalleriesInitialized}'-->

<!-- gallery id: gallery-1 -->
<div class="gallery" data-pswp>
  <a href="img1.jpg">
    <figure>
      <img src="thumb1.jpg" alt="">
      <figcaption>caption 1</figcaption>
    </figure>
  </a>
  <a href="img2.jpg">
    <figure>
      <img src="thumb2.jpg" alt="">
      <figcaption>caption 2</figcaption>
    </figure>
  </a>
</div>

<!-- gallery id: gallery-2 -->
<div class="gallery" data-pswp>
  <a href="img3.jpg">
    <figure>
      <img src="thumb3.jpg" alt="">
      <figcaption>caption 3</figcaption>
    </figure>
  </a>
  <a href="img4.jpg">
    <figure>
      <img src="thumb4.jpg" alt="">
      <figcaption>caption 4</figcaption>
    </figure>
  </a>
</div>

Triggers

If a specific element outside of the gallery needs to trigger it (let's suppose a gallery cover or a button), just define a data-pswp-trigger="GALLERY_ID".

Example:

<button data-pswp-trigger="gallery-1">
  Open first gallery
</button>

<button data-pswp-trigger="gallery-2">
  Open second gallery
</button>

It's also possible to a trigger to open a specific gallery item by appending a @ITEM_INDEX:

<button data-pswp-trigger="gallery-1@3">
  Open gallery (id: gallery-1) at fourth item (index: 3).
</button>

Options

Options can be defined in three ways:

• Extending the default global options by setting the third parameter of PhotoSwippy.init() call;

• Calling the PhotoSwippy.build(elementOrSelector, options) manually from your code;

• Passing the options object as the json data attribute data-pswp-options. Ex: data-pswp-options='{"key":"val", "key2":"val2"}';

• Passing a data-pswp-{key}="value" attribute for overriding a single property.

Photoswippy options

{
  /** Gallery item selector */
  itemSelector: 'a',
  /** Caption selector */
  captionSelector: 'figcaption',
  /*
   * Gallery item index selector.
   * Denotes the elements photoswippy uses to detect which item number the user has interacted with.
   * If a gallery uses, let's say, a slider, you can define it as the slide selector.
   * If 'null', photoswippy automatically uses the direct children of the gallery element.
   */
  indexSelector: null,
  /** If 'true', the mouseover on a gallery item will preload the image */
  hoverPreload: false,
  /** If 'true', the src of the thumbnail image (if it exists) will be used as thumbnail for photoswipe (msrc option)*/
  useMsrc: true
}

Each option is overridable with a data attribute like: data-pswp-option-name="value"

For other options, please refer to the PhotoSwipe Documentation.

Browsers support ^{_{made by godban}}

IE / Edge	Firefox	Chrome	Safari	Opera
10+	4+	13+	5.1+	12+