ScalableLightbox

A jQuery plugin for building aesthetically minimalistic, responsive picture lightboxes. Features an index module for providing an overview with thumbnails as well as a lightbox module, for displaying high-res images in a responsive manner.

Download Plugin View on GitHub Currently v1.0.1

Features

  • Retina ready
  • Responsive and touch optimized
  • Hardware accelerated CSS3 animations
  • Simple integration
  • Integrated image preloader
  • Highly optimized code
  • Comprehensive documentation
  • Multiple demos

Install

ScalableLightbox is a jQuery plugin, which means you have to integrate the jQuery library (v1.7.1+ or even v2.0.0+) on your website. Then include one of the following versions of the plugin depending on your purpose: 


<!-- ... -->

<script type="text/javascript" src="js/jquery-1.11.1.js"></script>
<script type="text/javascript" src="js/jquery.scalable-lightbox.js"></script>

<!-- ... -->

Bower

Even easier, you may install ScalableLightbox via Bower: 

bower install scalable-lightbox

Enabling touch support

You will need two more Javascripts, to run nicely on touch devices:

Download Modernizr with touch and csstransitions features enabled and integrate it in the header of your page, like so: 

<!DOCTYPE html>
<!--[if lt IE 7]> <html class="no-js lt-ie10 lt-ie9 lt-ie8 lt-ie7" lang="en"> <![endif]-->
<!--[if IE 7]>    <html class="no-js lt-ie10 lt-ie9 lt-ie8" lang="en"> <![endif]-->
<!--[if IE 8]>    <html class="no-js lt-ie10 lt-ie9" lang="en"> <![endif]-->
<!--[if IE 9]>    <html class="no-js lt-ie10" lang="en"> <![endif]-->
<!--[if gt IE 9]><!--> <html class="no-js" lang="en"> <!--<![endif]-->
  <head>
    <meta charset="utf-8" />

    <!-- ... -->

    <script type="text/javascript" src="js/modernizr.min.js"></script>

    <!-- ... -->

Then include the jQuery version of Hammer.js before integrating the ScalableLightbox: 

<!-- ... -->

<script type="text/javascript" src="js/jquery.hammer-full.min.js"></script>
<script type="text/javascript" src="js/jquery.scalable-lightbox.js"></script>

<!-- ... -->

That's it. ScalableLightbox will notice that you have all it takes to activate touch support.

Enabling hardware accelerated animations

The plugin also uses Modernizr to detect CSS3 transitions. Therefore integrate Modernizr like previously described with at least the csstransitions feature activated. This is everything ScalableLightbox needs to activate hardware accelerated animations.

License

Open source license

For personal, non-commercial, or open source projects and applications, you may use this software under the terms of the GPL v3 License. In short, this means you may use ScalableLightbox for free.

Commercial license

ScalableLightbox may be used in commercial projects with the one-time purchase of a commercial license. Tell me more.

Once purchased, you will receive a commercial license PDF and you will be all set to use ScalableLightbox for the number of domains you have purchased it for.

Buy Single Domain License $9
Buy 5 Domains License $19
Buy Unlimited Domains License $89

Getting started

HTML

You do not have to create any markup, because the plugin will do that for you.

CSS

The plugin's markup needs styling, which comes in two versions, depending on your purpose:

It's best to embed it before your own styles, so that you can easily overwrite them: 

<head>
  <meta charset="utf-8" />

  <!-- ... -->

  <link rel="stylesheet" href="css/jquery.scalable-lightbox.css" />
  <link rel="stylesheet" href="css/my-styles.css" />

  <!-- ... -->
</head>

For example, for the demos on the current page (index module and here for the lightbox module), we use the following styles to overwrite the default behavior: 

/* both overlays should have a white, non-transparent background */
.sl-index-overlay,
.sl-lightbox-overlay {
  background: #fff; opacity: 1;
}

/* the captions for the index module should be in black color */
.sl-index-item-caption {
  color: #000;
}

/* same for the three captions of lightbox module */
.sl-lightbox-caption-container {
  color: #000;
}

/* we use links in the lightbox captions, so we should style those */
.sl-lightbox-caption-container a,
.sl-lightbox-caption-container a:visited {
  color: #000;
}
.sl-lightbox-caption-container a:hover {
  border: 0; color: #333;
}

For more information on how to tweak the looks of this plugin, check out design.

Javascript

The Javascript part is where the magic happens. It is used to:

  • configure the plugin (checkout options)
  • feed it with images and captions (see data settings)
  • bind events used to display the plugin (checkout methods)

The configuration as well as the feeding of data is done on the initial plugin call. To feed data, there are two options (either directly via data attribute or by pointing to a JSON source via the api attribute). Here we go for the direct method and make use of the defaults, so the amount of configuration is reduced to the max: 

$(function() {

  $.ScalableLightbox({
    debug:       true,
    hash:        false,
    baseImgPath: "/assets/img/lightbox/",
    data: [
      { // deck with id: 1
        id: 1,
        items: [
          {
            img:     "canyon-house/01.jpg",
            width:   1500,
            height:  2173,
            caption: "Canyon House 01.jpg by <a href=\"http://www.labics.it\" target=\"_blank\">Labics</a>"
          },
          {
            img:     "canyon-house/02.jpg",
            width:   1500,
            height:  2173,
            caption: "Canyon House 02.jpg by <a href=\"http://www.labics.it\" target=\"_blank\">Labics</a>"
          }
          // additional item objects ...
        ]
      },
      { // deck with id: 2
        id: 2,
        items: [
          {
            img:     "italpromo/01.jpg",
            width:   1500,
            height:  2173,
            caption: "Italpromo 01.jpg by <a href=\"http://www.labics.it\" target=\"_blank\">Labics</a>"
          },
          {
            img:     "italpromo/02.jpg",
            width:   1500,
            height:  2173,
            caption: "Italpromo 02.jpg by <a href=\"http://www.labics.it\" target=\"_blank\">Labics</a>"
          }
          // additional item objects ...
        ]
      }
    ]
  });

});

As you can see, the plugin may display multiple lightboxes, which we call decks. Each item object of a deck needs to have at least an img, width and height attribute (see data structure for more information).

After the initialization, you may bind events to open a specific deck via its id in either the module "index" or "lightbox" according to your required behavior (see open method). For example: 

// open the index module of the deck with ID: 1
$("a.show-index").click(function(e) {
  e.preventDefault();

  $.ScalableLightbox("open", { module: "index", deck: 1 });
});

// open the lightbox module of the deck with ID: 2
$("a.show-lightbox").click(function(e) {
  e.preventDefault();

  $.ScalableLightbox("open", { module: "lightbox", deck: 2 });
});

That is exactly the behavior that is used on the current page. For more information, head to the options, methods and design page or learn more via examples.

In the wild

Are you using ScalableLightbox? Tweet @bh_oh or send an email to oh@baenziger-hug.com to possibly get featured here.

Buy Plugin