Last activity 07 Feb 2024 7 6 21437
composer require jonnitto/photoswipe

PhotoSwipe for Neos CMS


Release Date
Feb 07, 2024 14:59
  • #flow
  • #image
  • #photo
  • #gallery
  • #neos
  • #lightbox

Latest stable version Total downloads License GitHub forks GitHub stars GitHub watchers GitHub followers Follow Jon on Twitter


This package includes PhotoSwipe into Neos CMS

Version Neos Maintained
0.* 2.*
> 1.4 3.* + 4.*
2.* 3.3 + 4.*
> 3.* 3.3 + 4.*
>= 3.1.2 3.3 - 7.*

Screenshot of PhotoSwipe

Needed Markup

In consider to work, a link need to have the class lightbox and some data- attributes. If an image is inside the link, this image is used for small thumbnail for an faster UI experience.


This attribute is used for the caption in the lightbox. If this is not given, it search inside the link for a figcaption and uses this as caption. This is also a great way if you want to have HTML some markup inside your caption.


The size of the image to enlarge, e.g. 2560x1200. Example:

<a class="lightbox" data-size="2560x1200" href="path/to/image.jpg">...</a>

An alternative Markup would be:


data-ratio and data-ratio-image

If it not possible the get the size of the enlarged image (e.g. because the image is set to async), you can pass also data-ratio or data-ratio-image. Be aware, that this works best if you also pass the data-width (for zooming purposes). data-ratio-image can be a small version of the image (e.g. 100px wide). If this is given, it tries to get the dimensions and calculate the ratio from the filename. If this is not possible, the image get loaded and the ratio is calculated with naturalWidth and naturalHeight. After the first time an asnc picture is loaded, Neos replace the path width the filename where the ratio can be calculated without downloading the image.


If you want to open an image with the webp format you can pass it here (if the browser supports it)

Javascript variables

There are three global variables who get set during the intialisation:

PhotoSwipe The prototype from PhotoSwipe
PhotoSwipeUI The prototype from PhotoSwipeUI
neosPhotoSwipe This object stores some informations and functions who can help you achive your requirements:

Path Description
defaults The default settings for PhotoSwipe (you can adust them in the Settings.yaml file)
pswp This is a reference to the markup of the lightbox
dataset The dataset of the pswp element
open(items, options) With this function you can open a lightbox via javascript
init({ gallery, lightbox }) With this function you can initalize a new gallery. Normally this get called automatically.
initDom() This function calls init() if dataset.init is set to true
gallery This is a reference to the object created with new PhotoSwipe()

Javascript events

There are several events who get fired and you can react on. The events contains also some data like the instance, etc.

Event Description This event is fired before the code from gets exectued. This event is fired after the code from was exectued.
neosPhotoSwipe.init.before This event is fired before the code from instance.init gets exectued.
neosPhotoSwipe.init.after This event is fired after the code from instance.init was exectued.
neosPhotoSwipe.initDom.before This event is fired before the code from instance.initDom gets exectued.
neosPhotoSwipe.initDom.after This event is fired after the code from instance.initDom was exectued.


Most of the time you have to make small adjustments to a package (e.g. configuration in Settings.yaml). Because of that, it is important to add the corresponding package to the composer from your theme package. Mostly this is the site packages located under Packages/Sites/. To install it correctly go to your theme package (e.g.Packages/Sites/Foo.Bar) and run following command:

composer require jonnitto/photoswipe --no-update

To install the package under Neos 2.* you have to enter

composer require "jonnitto/photoswipe:^0.2" --no-update

The --no-update command prevent the automatic update of the dependencies. After the package was added to your theme composer.json, go back to the root of the Neos installation and run composer update. Et voilà! Your desired package is now installed correctly.


Licensed under MIT, see LICENSE

The content of the readme is provided by Github
The same vendor provides 19 package(s).