Roots Discourse

How To: ekko-lightbox and Sage 9

Ekko Lightbox is a super nice, Bootstrap-friendly lightbox library that can easily be made to play well with Sage 9 and WordPress galleries. Check it:

Install Ekko Lightbox

$ yarn add ekko-lightbox

Import in Javascript

At the top of the appropriate route (probably common.js), import ekko-lightbox:

import 'ekko-lightbox/dist/ekko-lightbox.js';

Add your javascript

In the same route, probably in finalize, add your custom javascript:

* Prevent default click behavior on WordPress gallery image links
$(document).on('click', '.gallery-item a', function(event) {

// Make an ekko lightbox out of WordPress galleries
$('.gallery a[href]')

// Test whether this link is directly to an image file
.filter(function() {
  return /(jpg|gif|png)$/.test($(this).attr('href'));
}).each(function() {

// Get link attr
var link = $(this).attr('href');

// Get the image ALT text
var alt = $(this).find('img').attr('alt');

// Strip the file extension
var filename = link.substr(0, $(this).attr('href').lastIndexOf('.')) || $(this).attr('href');

// Get the index of just the filename without the path
var fileNameIndex = filename.lastIndexOf("/") + 1;

// Return just the filename without the path and without the extension
filename = filename.substr(fileNameIndex);

// Get the ALT text so we can use it as a caption ONLY if it's NOT the same as the filename!
// WordPress automatically uses the filename as ALT text if no caption or ALT is set, so we don't want to use it if they're the same.
var caption = (filename === alt) ? '' : alt;

// Get the gallery ID
var gallery = $(this).closest('.gallery').attr('id');

// Add ekko lightbox data-attributes
$(this).attr({'data-toggle': 'lightbox', 'data-gallery': gallery, 'data-footer': caption});


Optional: set the default gallery options to link to media files

By default, WordPress gallery items link to attachment pages, rather than media files. We can change this default in the admin.

Note: this will only change the default for newly created galleries; old galleries will maintain the settings they were created with!

Create a new file in app called galleries.php:

namespace App;

* Set default link type for WordPress galleries

add_filter( 'media_view_settings', function($settings) {
    $settings['galleryDefaults']['link'] = 'file';
    return $settings;

Update functions.php line 61 to add galleries:

}, ['helpers', 'setup', 'filters', 'admin', 'galleries']);

That’s it!


@MWDelaney, thanks for this, just the kind of lightbox I was looking for!

I’d like to point out that if you include the css in you main.scss file it gets all the intended styling, too, which also plays a part in the way the modal’s content is loaded.

In main.scss (I include node module imports above the theme’s partials):

@import "~ekko-lightbox/dist/ekko-lightbox.css";

With this imported the transition in works as per the documented examples.

1 Like

And add this to your common.js if you want to auto-apply it to all image links:

$('a[href]').filter(function() {
  return /(jpg|gif|png)$/.test( $(this).attr('href'))
}).attr({'data-toggle': 'lightbox'});

$(document).on('click', '[data-toggle="lightbox"]', function(event) {

I also needed to know when the active modal was a light box:

// lightbox
$('[data-toggle="lightbox"]').on('click', function(e) {
    onShow: function() {
    onHidden: function() {

NB: $('.ekko-lightbox').addClass('scale'); is my custom transition

1 Like

Hi! Anyone tried to fire the lightbox from a link without any image? For example:

<a class="gallery-link" data-toggle="lightbox" data-gallery="gallery-1">See The Gallery</a>

I couldn’t get the way.

Hi, I’m getting the following error when trying the above approach…

ekko-lightbox.js:97 Uncaught TypeError: Cannot read property ‘Constructor’ of undefined

this._isBootstrap3 = $.fn.modal.Constructor.VERSION[0] == 3;

Any ideas how to overcome this??

Figured it out… I hadn’t included the modal import in common.js

import 'bootstrap/js/src/modal';

Lovely stuff. I can say goodbye to my other lightbox gallery plugins.

By the way this requires some very slight modifications for Gutenberg:

  • The new classes are ‘.blocks-gallery-item’ and ‘.wp-block-gallery’
  • You also have to set ‘Link to’ as ‘Media File’ in the Gutenberg editor.
  • There is no ID on gutenberg galleries by default so you must modify the code to use an auto-generated ID: e.g. var gallery = “ekko-gallery”

I can’t this working with Gutenberg default Gallery block.
I have replace .gallery-item with .blocks-gallery-item'. And changed the ID to “ekko-gallery”`
Some of the gallery markup is appearing, on click, but the corresponding image isn’t appearing in it. Seems to be missing CSS styling as well.

Does the lightbox work with bootstrap 5?

Unlikely; the project has been archived by its original developer, and the above jQuery code won’t work with Bootstrap 5.