photoswippy v0.2.0
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
ordata-pswp-src
) - Size of image to be opened (
data-pswp-width
ANDdata-pswp-height
ORdata-pswp-size="WIDTHxHEIGHT"
) - Caption (
data-pswp-caption
or theoptions.captionSelector
HTML or the thumbnail'salt
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+ |