Greybox, Lightbox Part 2 | WebReference

Greybox, Lightbox Part 2

By Arpan Dhandhania

This is a second article in a series of articles on various implementations of Lightbox. In case you haven't read the first part, here it is: Shedding some light on Lightbox.

What is Lightbox?

"Lightbox is a simple, unobtrusive script used to overlay images on the current page. It's a snap to setup and works on all modern browsers."

Though this quote has been pulled out Lokesh Dhakar's implementation of Lightbox, it holds true for all its implementations. For more about Lightbox, read the first part of this series here.


Greybox is an implementation of Lightbox that allows you to display websites, images and other content in a HUD (heads up display). Why use Greybox?

  • It's super small, only 22KB!
  • It's easy to setup.
  • It's styled in CSS, so you can customize it to your taste.
  • It' doesn't conflict with pop-up blockers (please don't exploit this feature for commercial purposes :)


When we think of Lightbox, the first thing that comes to our mind is showing a bunch of images--and yes, that is one of the primary uses of Greybox.

Single Photos

Photo Album

Greybox offers another use of Lightbox, something that other implementations can't brag about. I am talking about displaying a website or web page in a div. Now you might be wondering why we would want to do this. Well, a very good example of this is the following:

Consider you are building a web application and you need a user to authenticate before performing a task. Instead of redirecting her to the login page and then bringing her back to this page, you could use Greybox to display a login form in a div. This is similar to when you are installing a new application on the Mac, you are asked for the Administrator password.

Since Greybox is modal, the user can't ignore the login form. She must either submit the form or cancel it. If she cancels it, she is taken back to the previous screen.

Another use of Greybox is if you want to display a map on your website. You can have a small map on the page, and when the user clicks on it, you can show a completely navigable large map using Greybox.

You could also use it if you wanted to simply display another website within a div. Honestly, I don't see any real-time use of this, but since Greybox, supports it, I will show you how to implement it.

Launch in a 640x480 window
Launch in fullscreen window

How to Use

1.  Specify the path to Greybox
First you need to download the Greybox library and place it somewhere in your web directory. Append the following lines in the HEAD section of your page from which you wish to invoke Greybox. GB_ROOT_DIR contains the path to where the static files are located.

Note: GB_ROOT_DIR should contain the absolute path. You only require the greybox folder for functionality; the other files are source files and documentation.

2.  Include Javascript files.
Greybox library is split into 3 Javascript files and one CSS file. We need to include them so that we can use them.

Note: AJS_fx.js is optional. It is used for effects. If you wish to speed up your site and don't want the effects, don't include AJS_fx.js.

3.  Done. Now let us use it.

  • Single image


  • Imageset


  • Website


I have only covered the regular use of Greybox, however, if you would like to tweak it a little, you can get more information about the advanced usage of Greybox here.

Compress Greybox Further

If you find that 22KB is still too big for Greybox; you can shrink it even further. It is a two-step process that requires you to have Java and Python installed on your system. Here are the steps to compress Greybox:

1.  Download Dojo ShrinkSafe
Make sure you have Java installed because you will use Dojo ShrinkSafe to compress Greybox. You need to download custom_rhino.jar and place it in Greybox's compression_lib directory.

2.  Compress Greybox
Compressing Greybox is done by executing the Python script called You can execute it in any one of the following ways:
- python fullscreen: to compress everything
- python gallery: to compress only gallery related CSS and JavaScript
- python window: to compress only window related CSS and JavaScript


So far, we have seen two implementations of Lightbox. The first one, Lightbox 2, supported slideshows, but did not allow us to display anything other than images. The second implementation allows us to display web pages in the Lightbox and its design is more customizable with CSS, but it doesn't do a great job with pictures. It doesn't even support a slideshow mode. This just goes to prove that we can't dismiss either one of them as redundant since both are useful in their own ways.

There are several implementations of Lightbox, most of which do the same thing. There is however, one more important use of Lightbox. We touched upon it in this installment, but the next article will speak in more detail about how you can use Lightbox to display modal dialog boxes.

Original: May 11, 2009