How to add Image Lightbox to Ghost Themes

First of all what is Lightbox? Lightbox is a basically a window overlay that appears on top of a webpage, usually dimming the background and bringing attention to the Lightbox content itself in our case the images.

There are many possible libraries that can be used to add this functionality to a Ghost Theme, in this tutorial we'll be using fslightbox. Why? Because it's in vanilla javascript (no jQuery dependency), it's lightweight and comes with a nice design out of the box.

Now, adding it to your Ghost Theme can be different depending on your Theme workflow, we usually work with gulp to bundle and minify all the javascript, but it can also be added directly.

Install via npm & gulp

This would be the more elegant approach, assuming you have a minimal knowledge about task runners such as gulp. You can also skip this and go with the direct installation instead.

First we install the package:

npm install --save fslightbox

Now we have to edit the gulpfile of the theme. We have a task which compiles all our javascript code and minifies it, this task looks something like this:

const asset_dist = 'assets/dist/';
const npm_src   = 'node_modules/';

// Handle Js
const js = done => {
  pump(
    [
      src([
        ... some other packages here ...
        `${npm_src}fslightbox/index.js`,
      ], { sourcemaps: true }),
      concat('app.js'),
      rename({suffix: '.min'}),
      uglify(),
      dest(asset_dist, { sourcemaps: '.' })
    ],
    handleError(done)
  );
};

Adding ${npm_src}fslightbox/index.js to the list of srcs will make sure that fslightbox will be included in the js bundle on the next build.

This task will also minify and put app.min.js in the dist folder.

Install directly

Another approach is to download the file, and add it either in your .hbs file or using the Ghost Admin Interface.

After you have downloaded the zip file, extract it and copy the fslightbox.js in the assets directory of your theme.

Next we have to link to this file from the template, so add the following line either in default.hbs of the Ghost theme or in the Site Footer section in Ghost Admin > Code Injection.

<script async src="{{asset 'fslightbox.js'}}"></script>

Now, the library is ready to be used.

Using the Lightbox

Next step is putting the library to use and setting it up, so images within a post will be available in the Lightbox.

We will add some code for this to work. Add the following lines (as previously) either in default.hbs or in your Ghost Admin Interface.

<script>
const images = document.querySelectorAll('.kg-image-card img, .kg-gallery-card img');

// Lightbox function
images.forEach(function (image) {
  var wrapper = document.createElement('a');
  wrapper.setAttribute('data-no-swup', '');
  wrapper.setAttribute('data-fslightbox', '');
  wrapper.setAttribute('href', image.src);
  wrapper.setAttribute('aria-label', 'Click for Lightbox');
  image.parentNode.insertBefore(wrapper, image.parentNode.firstChild);
  wrapper.appendChild(image);
});

refreshFsLightbox();
</script>

Let's explain the above coding:

• first line is simply selecting all images from image cards and galleries on the current page
• next we iterate through the found images and do the following
  • add a anchor tag as wrapper around the image
  • add the necessary attributes to the wrapper so fslighbox can use it
  • add the wrapper to the card/gallery element
  • add the image to this wrapper
• finally we refresh Lightbox to detect the new elements

That's it, the Lightbox should be working, as soon as you have an image card or gallery card.

Check a working example, just click on any image and the Lightbox should appear.