Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kaisermann/photoswippy

A no-(extra)-dependency PhotoSwipe friendly wrapper
https://github.com/kaisermann/photoswippy

Last synced: 16 days ago
JSON representation

A no-(extra)-dependency PhotoSwipe friendly wrapper

Host: GitHub
URL: https://github.com/kaisermann/photoswippy
Owner: kaisermann
Created: 2017-08-30T16:59:27.000Z (about 7 years ago)
Default Branch: master
Last Pushed: 2018-04-25T16:04:52.000Z (over 6 years ago)
Last Synced: 2024-10-08T16:46:52.771Z (about 1 month ago)
Language: JavaScript
Homepage:
Size: 103 KB
Stars: 12
Watchers: 5
Forks: 2
Open Issues: 0
Metadata Files:
- Readme: readme.md

Awesome Lists containing this project

README

# PhotoSwippy

[PhotoSwipe](http://photoswipe.com/) 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](https://github.com/yaquawa/jquery.photoswipe) and [photoswiper](https://www.npmjs.com/package/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`](http://photoswipe.com/documentation/getting-started.html) has the `pswp` class and it's already on the DOM.

### Module

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

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

### Browser

```html

photoswippy.init(PhotoSwipe, PhotoSwipeUI_Default, options)

```

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:**

```html

```

### 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:**

```html

Open first gallery

Open second gallery

```

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

```html

Open gallery (id: gallery-1) at fourth item (index: 3).

```

## 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

```js
{
/** 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](http://photoswipe.com/documentation/options.html).

## Browsers support _{^{_{_{made by godban}}}}

| [](http://godban.github.io/browsers-support-badges/)IE / Edge | [](http://godban.github.io/browsers-support-badges/)Firefox | [](http://godban.github.io/browsers-support-badges/)Chrome | [](http://godban.github.io/browsers-support-badges/)Safari | [](http://godban.github.io/browsers-support-badges/)Opera |
| --------- | --------- | --------- | --------- | --------- |
| 10+ | 4+ | 13+ | 5.1+ | 12+