🖼 Kirby Lightbox-Gallery by @wottpal
(Disclaimer: This is a pre-release.)
A plugin for the awesome Kirby CMS which allows the editor to easily inline beautiful galleries with lightbox-support.
- Dynamic & responsive Grid-Alignment
- Works with Kirby's built-in thumbnail class, ImageSet by @fabianmichael and Focus by @flokosiol
- Powered by PhotoSwipe by @dimsemenov
captionimage-fields directly into PhotoSwipe
- Configurable & Customizable to it's core
Because of the PhotoSwipe dependency multiple steps are necessary for a proper installation of the plugin. Also PHP 5.6+ is required. If you have any questions feel free to reach out or file an issue.
1. Install the plugin itself
Recommended: Use Kirby's CLI and install the plugin via:
kirby plugin:install wottpal/kirby-lightbox-gallery
Oldschool: Download this repo and move the folder to
2. Download Photoswipe
Download PhotoSwipe (tested version 4.1.2) rename the
dist directory to
photoswipe and place it under
Note: Additionally you should minify the two
.css files of PhotoSwipe which is weirdly not done by them. I love to use Squeezer for macOS for that. In the next section I'll assume that minified versions of these files exist.
3. Link Resources
Embed necessary styles within your
<?= css([ 'assets/plugins/lightbox-gallery/gallery.min.css', 'assets/vendor/photoswipe/photoswipe.min.css', 'assets/vendor/photoswipe/default-skin/default-skin.min.css' ]) ?>
Embed necessary scripts before the end of your
<?= js([ 'assets/vendor/photoswipe/photoswipe.min.js', 'assets/vendor/photoswipe/photoswipe-ui-default.min.js', 'assets/plugins/lightbox-gallery/init-photoswipe.min.js' ]) ?>
If you use the default initialization (
init-photoswipe.min.js) and want to support older browsers you may need to add polyfills for the
Except the PhotoSwipe Base CSS & JS you can literally replace every dependency with your own code. A good start for this is to copy & paste the original dependency (e.g.
'site/plugins/lightbox-gallery/src_assets/init-photoswipe.js') into your own assets folder, do your modifications and change the asset-paths accordingly. But be aware that the plugin changes over time and you may have to keep your changes compatible.
🏊 Usage Examples
(gallery: all) # Includes all images of the page (gallery: 1.png 2.png 3.png) # Includes only selected images (gallery: all page: projects/a) # Includes all images of the page with the given uri (gallery: all limit: 2) # Only shows thumbs of the first two images (gallery: all order: random) # Shuffles all images (gallery: all order: reverse) # Displays all images in reverse order (gallery: all cols: 2 4) # Sets cols to ['min' => 2, 'max' => 4] (gallery: all cols: 3) # Sets cols to ['min' => 3, 'max' => 3] (gallery: all mobilecols: 1 2) # Sets mobilecols to ['min' => 1, 'max' => 2] (gallery: all stretch: last) # Stretch trailing items instead of first (gallery: all stretch: none) # Disable stretching (gallery: all class: my-class id: my-id) # Applied a class & id to the gallery-wrapper
Please see the following section for further description how the particular parameters work. Options set in a Kirbytag always overwrite global options.
The following options can be set globally in your
c::set($key, $value = null). You can also set multiple keys with
c::set([$key => $value, ..]).
The name of the tag to use this gallery within kirbytext. Like
Specify an ID or class which is added to the gallery-wrapper element. Use it for custom styling.
If set to
true all galleries on one page will be virtually the same. So you can navigate between all images in the same lightbox.
Maximum amount of previewed thumbnails to be shown.
Note: The hidden items are only visually hidden with CSS. By appending a
data-not-previewed attribute to the
['min' => 3, 'max' => 4])
['min' => 2, 'max' => 2])
Defines the range of possible columns the gallery can choose of. Within this range an algorithm
Note 1: The actual implementation is located under
Note 2: The mobile-breakpoint and gutter-width are currently defined in
src_assets/gallery.scss. You can overwrite it by setting a
lightboxgallery.class and adding your own styles or completely substituting the plugins CSS with your own stylesheets.
*If there are not enough images to fill all rows with as many items as columns by default the images in the first row are stretched to fill up the whole width. You can set this option to
'last' to stretch all trailing items instead or set it to
'none' to disable stretching at all.
Choose from one of the following providers for thumb-creation:
'thumb'(Kirby's built-in thumbnail class)
'focus'(Kirby-Focus by @flokosiol)
false(just use the image as thumb)
Note: Because thumbnail-creation for a whole gallery may take some time and you don't want the first visitor of your site to suffer I recommend you to have a look into ImageKit.
["width" => 800, "height" => 800, "crop" => true])
Define the options for the selected
thumb.provider. Works exactly the same way as you would use the options with their respective functions. If you set the
thumb.provider to something else than
false you must set this option.
Note 1: The default-value is crops 800x800 thumbnails with Kirby's built-in thumbnail class.
Note 2: If you use
focus put all values in an array. So for example if you set it to
[300,300] the plugin will call
Note 3: If you use
imageset you set this option to something like
['400x400-1000x1000, 4'] to generate responsive square images. (You should specify
sizes as well).
Have a look at the releases page.
- Possibility to define thumb-sizes for the Non-ImageSet version
- Option to move stretched row to the end (only if
count % col != 0)
- Option to not stretch row and keep the same column-count (only if
count % col != 0).
- Allow cols/mobilecols to be set in the kirbytag
- Think more about non-square images
- Dynamic thumb-options based on column-count
- Define responsive image-sources for PhotoSwipe
- Option to disable lightbox usage
- Enable use of History-API of PhotoSwipe in init-photoswipe.js
- Maybe a new breakpoint-based API for defining min/max cols like
- Support for videos (esp.
For minification and transpilation I use Gulp. Please note that all files under
assets/ are only the generated ones from
# Install Dependencies npm i # Or: Install Dependencies for Hipsters yarn # Build & Watch (Install 'gulp-cli' globally to omit the 'npx') npx gulp
Just kidding. This plugin is totally free. Please consider following me on Twitter if it saved your day.
You can also check out one of my other Kirby-plugins: