Lightbox Slideshow

by Justin Barkhuff,


Lightbox Slideshow is a simple, unobtrusive script used to overlay images on the current page.

It’s basically a better version of Lightbox2. In fact, the technical requirements and installation steps are identical to Lightbox2, but with Lightbox Slideshow, the underlying code is much better and there are lots of useful configuration options.

Here are just a few things you can do with Lightbox Slideshow that you can’t do with Lightbox2:

  • auto-playing slideshow
  • navigate images via ‘prev’ and ‘next’ links in the image caption area
  • when browsing a group of images, go from the last image to the first image (and vice versa)
  • track individual image views using Google Analytics
  • move the caption above the image
  • customize the interface language

See the configuration options section for more.


If this code just saved your life and you want to thank me with some of the money you just saved, I’m not above accepting donations:


Single image

Group of Images


Version 1.1, released August 15, 2007

If you are using Prototype 1.6, replace lightbox.js with the Prototype 1.6 compatible lightbox.js

All users of Version 1.0 should upgrade to this new release. See the Change Log for details.


If you are already using Lightbox2, just replace your existing lightbox.js and lightbox.css files with the ones included in the download. Be sure the image references in the CSS file are correct.

Part 1 - Download and Test

The downloadable zip file contains all files required to run Lightbox Slideshow and the sample page and photos.

After downloading the zip file, extract all the files to any directory on your computer and upload that directory anywhere on your site.

You should then be able to view this functioning sample page at:

If you are using Prototype 1.6, replace lightbox.js with the Prototype 1.6 compatible lightbox.js

Part 2 - Setup Your Own Page

Lightbox Slideshow uses the Prototype Framework and Scriptaculous Effects Library. You will need to include these three Javascript files in your header (in this order).

<script type="text/javascript" src="prototype.js"></script> <script type="text/javascript" src="scriptaculous.js?load=effects"></script> <script type="text/javascript" src="lightbox.js"></script>

Include the CSS file (or append your existing stylesheet with the Lightbox Slideshow styles).

<link rel="stylesheet" href="lightbox.css" type="text/css" media="screen" />

Check the CSS and make sure the referenced image files are in the right location.

Part 3 - Activate Links

Add a rel="lightbox" attribute to any link tag to activate the lightbox. For example:

<a href="images/image-1.jpg" rel="lightbox" title="my caption">image #1</a>

Optional: Use the title attribute if you want to show a caption.

If you have a set of related images that you would like to group, include a group name between square brackets in the rel attribute. For example:

<a href="images/image-1.jpg" rel="lightbox[roadtrip]">image #1</a> <a href="images/image-2.jpg" rel="lightbox[roadtrip]">image #2</a> <a href="images/image-3.jpg" rel="lightbox[roadtrip]">image #3</a>

There are no limits to the number of image sets per page or how many images are allowed in each set. Go nuts!

Keyboard Shortcuts

  • f for first image
  • l for last image
  • x and c to close
  • left arrow and p for previous image
  • right arrow and n for next image
  • s to toggle the slideshow

Configuration Options

Lightbox Slideshow allows you to easily configure a number of options. Configuration options are specified by passing an object of your configurations to the Lightbox.initialize() method. This involves editing the last line of the lightbox.js file.

Here are the configuration options:

  • animate : resize animations; defaults to true
  • autoPlay : should slideshow start automatically; defaults to true
  • borderSize : if you adjust the padding in the CSS, you will need to update this variable; defaults to 10
  • containerID : lightbox container object; defaults to document
  • enableSlideshow : enable auto-playing slideshow feature; defaults to true
  • googleAnalytics : track individual image views using Google Analytics (requires Google Analytics code to be installed); defaults to false
  • imageDataLocation : specifies the location of the caption information (north or south of the image); defaults to south
  • initImage : ID of image link to automatically launch when upon script initialization; defaults to an empty string
  • loop : whether to continuously loop slideshow images; defaults to true
  • overlayDuration : time to fade in shadow overlay; defaults to .2
  • overlayOpacity : transparency of shadow overlay, can be any value between (and including) 0 and 1; defaults to .8
  • prefix : ID prefix for all dynamically created html elements; if you change this, you must also update the CSS selectors in lightbox.css; defaults to an empty string
  • relAttribute : string that specifies the rel attribute value that triggers lightbox; defaults to 'lightbox'
  • resizeSpeed : controls the speed of the image resizing (1=slowest and 10=fastest); defaults to 7
  • showGroupName : show group name of images in image details; defaults to false
  • slideTime : time (in seconds) to display images during slideshow; defaults to 4
  • strings : object that allows for localization; when customizing this, all string object properties must be defined; defaults to:
    { closeLink : 'close', loadingMsg : 'loading', nextLink : 'next &raquo;', prevLink : '&laquo; prev', startSlideshow : 'start slideshow',stopSlideshow : 'stop slideshow',numDisplayPrefix : 'Image',numDisplaySeparator : 'of' }

Sample Configurations

Do you use Google Analytics? Here is a sample configuration that enables tracking of individual image views. This line of code would replace the last line of your lightbox.js file:

Event.observe(window,'load',function(){ Lightbox.initialize({googleAnalytics:true}); });

Here is a sample configuration that shows the group name for groups of images and disables the autoPlay slideshow setting. Remember, this line of code would replace the last line of your lightbox.js file.

Event.observe(window,'load',function(){ Lightbox.initialize({showGroupName:true,autoPlay:false}); });

Is your site in German? Here is a sample configuration that uses German-specific strings. These lines of code would replace the last line of your lightbox.js file:

var lbStringsDE = { closeLink : 'ende', loadingMsg : 'laden', nextLink : 'weiter &raquo;', prevLink : '&laquo; zur&uuml;ck', startSlideshow : 'start diashow', stopSlideshow : 'stopp diashow', numDisplayPrefix : 'Bild', numDisplaySeparator : 'von' }; Event.observe(window,'load',function(){ Lightbox.initialize({strings:lbStringsDE}); });

Change Log

Version 1.1 (released August 15, 2007)

  • Fixed a bug in Firefox that would cause an error if no ’title’ attribute was found for a Lightbox Slideshow enabled link (thanks Patrick Weyers)
  • Added support for the ’initImage’ configuration option
  • Added support for the ’loop’ configuration option

Version 1.0 (released July 27, 2007)

  • First official release!