jQuery.popeye – an inline lightbox alternative

jQuery.popeye 2.0 has been released. Older Versions are no longer supported.

Writing the history of single-page image galleries on the web, one could start like this:

In the beginning, there was nothing. And the Developer said: “Let there be pop-ups!” And the Users saw that pop-ups were bad…

Then came Lightbox. Finally, an unobtrusive script allowed to display enlarged versions of thumbnail images embedded in web pages without leaving that web page or breaking the layout. The “simple” solution was to add a semi-transparent overlay to the page, on which the enlarged image is centered.

Since then, we’ve seen a ton of similar scripts used on an ever-increasing number of websites.

While at first, I, like everyone else, was really enthusiastic about this technique, I have come to see some of the downsides of a lightbox-ish image presentation:

  • Lightboxes are usually not consistent with the look & feel of the rest of the website, and
  • they still feel like a kind of pop-up, since the image leaves the layer of the web page and opens up a new layer.

Besides – I’m getting tired of seeing the same effect, the same UI controls over and over…

So, while working on a client project in which I at first used a jQuery Lightbox plugin, I ended up dissatisfied with the outcome. I had gone through great length to stir up a consistent look & feel, just to see it vanish under the lightbox overlay.

I wanted something more integrated in the flow of the web page – a box with a small preview image with caption, the possibility to flip through an array of more thumbnails and, of course, to show an enlarged version, all in one place. Lightbox offers that. Moreover, I wanted the box to stay anchored to the page layout and not hovering above it disconnectedly. The way to achieve this was writing a script which would fix one corner of the enlarged image to the exact spot where the thumbnail had been.

After toying around for a while, I decided to put the final outcome into a proper jQuery plugin and see, what other people (you!) think. May jQuery.popeye be of use!


The plugin transforms an unoredered list of images into a box displaying only one preview image at a time. The box has controls to skim through the preview images and to enlarge a given image. The box expands to accomodate the enlarged version, while the controls are hidden in full image size mode. A simple click on the image returns the box to its compact state.

The compact box has fixed, automatically calculated dimensions. The widht and height are calculated so that all thumbnail images are cropped to the smallest width and height in the set and centered resulting image area (stage).

This behaviour can be overriden in the plugin options.

I have set up a demo page which best shows the behavior of jQuery.popeye.


jQuery.popeye degrades gracefully into a scrollable list of thumbnails which link to an enlarged version. The HTML-setup should look like this:

Once the plugin has been included in your web page, the popeye(es) can be easily created with the following command:

$(document).ready(function () {

Of course, multiple popeyees can be used together on a single page.


jQuery.popeye supports a wide range of options. They are, in detail:

Option Type Default Description
stageW string n/a override width of compact image stage (e.g. '200px')
stageH string n/a override height of compact image stage (e.g. '200px')
jclass string 'popeye-hasjs' class to be applied to popeye-box when the browser has activated JavaScript (to overwrite fallback styling)
eclass string 'popeye-haspopped' class to be applied to enlarged popeye-box
lclass string 'popeye-isloading' class to be applied to stage while loading image
direction string 'left' direction that popeye-box opens, can be 'left' or 'right'
duration integer 400 duration of transitional effect when enlarging or closing the box
easing string 'swing' easing type, can be 'swing', 'linear' or any of jQuery Easing Plugin types (Plugin required)
nlabel string 'next' label for next button
plabel string 'previous' label for previous button
oflabel string 'of' label for image count text (e.g. 1 of 14)
blabel string 'enlarge' label for enlarge button
clabel string 'Click to close' tooltip on enlarged image (click image to close)

Update: These are the options for jQuery.popeye 0.2. The options for the latest version have changed!

To overwrite the default parameters, you can use the following code:

var options = {
	direction:  'right',
	duration:   230,
	stageW:     '200px',
	stageH:     '240px'

The plugin comes with the mandatory css-file jquery.popeye.css which shouldn’t be altered. Additionally, I have included a second, customizable CSS-file with an example style for you to build upon.

I repeat…

Download jQuery.popeye
from the jQuery Plugin Repository


There are still some issues with the first release of jQuery.popeye which I hope to resolve in future versions. They mainly concern the size of the enlarged box (the whole image should stay visible) and the gallery controls (will introduce proper controls to enlarged box).

But for now, your feedback, bug reports, improvements and feature requests are very welcome in the comment section.

“I yam what I yam!” — Popeye

jQuery.popeye 2.0 has been released. Older Versions are no longer supported.

104 thoughts on “jQuery.popeye – an inline lightbox alternative

  1. I’m having big problems getting multiple popeyes on a single page. It’s probably my fault. styling.css is set up with #popeye1, and I want them all to look that way, but I can’t give them all the same ID, so I change #popeye1 to .popeye1 and give all my popeyes the same class name. When I load the page, they all disappear!

  2. To have multiple popeyes on the same page, look at the example/demo. You’ll need to make a #popeye2 or 3 or whatever you want to call it. You will also have to make sure the styles for the additional popeyes are defined in your css styles.

    Note about multiple popeyes: Make sure that the 2 (or 3 or whatever) popeyes aren’t next to each other where the expanded images will overlap another popeye — it causes weird overlapping results. (see my comment #85)

  3. @junior: I would really be surprised if the w3c-validator would let you validate js-generated code. Try fixing your own code first ;-)

    @khalil: It works with any list of images, no matter what the source is. They just have to be in the correct format as an unordered list.

    @jtnatoli: You don’t need to do the styling via IDs if you want to use one style only. Just apply the rules to the class .popeye and subsequent classes.

    @all: I started working on an update, so all the above mentioned bugs schuold be fixed soon. The update will also feature a revised user interface and base style.

Comments are closed.