jQuery.popeye – an inline lightbox alternative

Posted on by
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!

Behavior

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.

Usage

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 () {
	$('.popeye').popeye();
});

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

Customization

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'
}
$('.popeye').popeye(options);

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

Considerations

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. Hi there!
    It works in Safari on Mac, but in Camino it doesn’t work – don’t know if it can be fixed?

  2. Interesting, but doesn’t work properly in Firefox 3.1 B2 or Opera 10 A1 – the problems are visually obvious.

  4. Hi There,

    This looks very good and something I will consider using the the future, however; it doesn’t work with Google Chorme :(

    Cheers
    Stephen

  5. Again, thanks to all for your comments. There will be a new release coming January, I hope, which will address all the bugs you have mentioned and also feature some new skins and interface features. Untill then, I will keep reading your comments here, but as I´ll be traveling, won´t have time to answer them.

  6. Very Great Plugin, but if u open an image, close it and open it again without navigating through, only the preloader is visible, the image doesn’t load again.

  7. Wow, großartig! Ich denke gut 50% aller Projekte die ich bislang mit ner lightbox oder lightbox-Alternative versehen hab hätten von diesem Script viel mehr profitiert!

    Vielen Dank für das tolle Plugin, definitiv ein must-have und endlich mal eine gute und praktische Umsetzung des lightbox-trends!

  8. Very great work, nice to use in my projects, but if you open an image close an open it again, the image doesnt load again :( its a bug?

  9. Good job, nice tool!

    Many thanks from Italy, I’ll be waiting the next release with the fixed bugs on Opera and IE.

    =)

  10. Found your link from webappers.com, and withoutlooking into the demopage to much at first glance it looks promising. However, as a programmer, there are issues here which need to be taken care of before really doing anything with this script.

    First of all there is atleast a major bug in IE7, since this after all is THE browser of choice statistically I see no reason in checking in other browsers. As a few mention here, clicking the same image twize and you end up in a preloading limbo. This bug renders your plugin usesless, however a great proof of concept. I believe you should patch this one ASAP unless you want alot of users losing interest in you, getting burned on using your plugin… Just some advice!

    On some more useful comments from my perspective I would love to see the following:
    - A smarter sollution for CSS or something, to prevent that jumpy feeling on your first visit of the page. Say BMW should use the plugin on their page, I would only guess this is minimum requirement
    - What’s up with those scrollbars? While it is nice that your plugin atleast handles larger text without exploding, your examples would look so much better by not having the scrollbars.
    - When the image is popped, clicking anywhere should be default behaviour to close the image. After all, you do not want to keep surfing whith a huge image hanging all over the page.
    - Image captions. The enlarged image should be able to have a HTML section bottom/top/left/right of it. Being able to choose this with something like would be great.
    - Does it handle video? Not a requirement, however nice to know if you want to go for it or not.
    - Is your plugin tested against pulldown menus? (iframe trick)

    Other than that, great proof of concept. Looks promising – keep it up!

  11. I like your approach and would like to contribute some code. It would be useful if you could post (or drop me a line) a timeline of which issues/features you’ll address and when, so that we don’t end up doing the same things.

    Cheers

  12. This is excellent work. Judging by the comments I don’t think it’s quite ready for my commercial projects yet, but I’ve bookmarked you and will be eagerly awaiting future releases.

    Meanwhile, I’ll have fun with it in my personal projects.

    A small note: your chosen font size for this page is very small – I had to increase twice to read comfortably. A slightly larger and clearer font would be a great move (and preferably not one of these new horrible Microsoft Vista ones that have sub-pixel hinting ;).

  13. Beautiful work, these are the kinds of widgets that people should be making! I can definitely see this being useful on shopping websites, where every product page has a small image that can then be enlarged – with this, enlarging the picture does not require loading a new page, and multiple views can be presented!

  14. Great plugin but unless you can fix for IE7 useless for practical deployment (clicking on the thumbnail provides only loading graphic).

  15. Hi there,

    Great script! Here’s the fix for the caching issue in IE7, IE8 and Opera ;-) It seems that the onload event for the preloader is attached AFTER the preloader src is set. IE and Opera load the image from the cache quickly and before the event is attached. To make the long story short – find the following code:

    var preloader = new Image();
    preloader.src = im.large[i];
    // once image has loadded…
    preloader.onload = function()
    {
    ………….
    };

    and change it to:

    var preloader = new Image();
    // once image has loadded…
    preloader.onload = function()
    {
    ………….
    };
    preloader.src = im.large[i];

  17. Wonderful idea and the implementation is really neat, congrats.

    Some comments:
    - is there a way to not hide the controls when the image is maximezed ? If not, it really should be possible.
    - keyboard navigation for next/previous and escape to close the full sized image could be a really nice and subtle complement

  18. Hello.

    I’m trying to figure how to modify the CSS but i’ve some troubles with the enlargement one.

    When I press “Enlarge” it fits de large image moving down other divs that I have in the same place, and when I click to select another, the layout gets all messed up.

    here are some pics. I’m testing on my pc so, no place to link. Sorry about that.

    1.- Just loaded: http://img227.imageshack.us/my.php?image=snap0076tl0.jpg
    2.- Clicked Enlarge: http://img71.imageshack.us/my.php?image=snap0077xt6.jpg
    3.- When i click to go back to the thumbpic: http://img71.imageshack.us/my.php?image=snap0078tg5.jpg

    You can see the div got all messed up. I’m not a CSS expert so i guess there’s something odd about the way the layout is formed. But till now i can’t figure out what’s wrong.

    I need your help. Hope to hear from any of you soon.

    Have a happy new year.

    Bye!

    Greetings from Chile

  19. Great job, Christoph Schüßler….I don’t know how to express my earnest appreaciation. I have searched this kind of advance jquery script for my photo gallery quite a long time already. I found some advance jquery before, but those script very hard to implement, somemore the function can not satisfied my requirement. But your one is different. I can really say that your script is the most easiest to understand and implement (for me, because i am a noob). You are amazing. To Emil, thanks for your fix for IE7, IE8 and Opera. Keep it up! (Pls forgive for my poor english.)

  20. Hi all,
    I was really trying to look for a solution among the comments..but I did not really understand how can it works for you with all the others browser..
    For me it only works with FF … :S
    is there a fix I should apply?! (to css maybe?)
    this is my test-page: http://www.eyesofrome.com/tour_vatican.php
    what’s wrong?!
    (it tried both stiles given with the plugin)

  21. @adedip: I had the same issue before.

    If you load dynamic pictures, you must give the width and height of each one in the tag. So that way the jquery script can translate the values and set the CSS properly.

    Hope it works!

    Silla!

  22. @ sciyfox: thx for replying

    do u mean like this:

    this solution solved partially the problem.. still have probs with IE6 (it keeps the box width now..but doesn’t show picturs) and with IE7 (it kind of work..but does strange effects on popups..)

    any clue? (check the page link above to understand what I’m saying)

    thanks a lot anyway to you all for making this works
    happy new year!

  24. Hello again.

    Sadly i had to switch to Thickbox. I Needed to load full subpages instead of just pictures.

    Anyway, to keep with the adedip issue:

    try this:
    # var options = {
    # direction: ‘left’,
    # $(‘.popeye’).popeye(options);

    in the options.

    If you have issues with IE, maybe you should use CSS hacks to make it work.

    HAve a nice 2009 too!

  25. Can we have pop out lightbox to load full subpages instead of just pictures? As a user’s view, i prefer lightbox to view all the images. This method more efficient and user friendly.

  26. @ Scyfox
    so..what about keeping popeye as it is just changing the popus into something like lightbox or thickbox..taking off the visual layer effect around the pic popped up? It might solve the problems…

    thanks anyway for your job man! ;)

  29. @adedip

    Looks like it was my mistake. I forgot to put the wmode parameter to the flash object, so now it loads. But still doesn’t fit my needs since i ‘ve to display a full html page and not just images.

    Anyway at least i figure out what was wrong.

    Good to know that you came back ok, Chris.

    Silla!

  30. “A small step for men, a big step for the world” .. :D

    that might be a solution anyway (at least for know)

    just let us know when u’ll release the latest version ;) thx for your work!

  31. Love it! I’ve been so tired of the everyday lightbox and this fits my need.

    Any way to use the popeye on a single image and not an entire gallery and hide/disable the navigation controls?

    Any way to call the script from an ?

  34. Great plugin. Just what I was needing for a small project.

    One thing I noticed though: If you have 2 popeyes on a page (for example, side by side) and the 1st image (say on the left) expands over the other popeye, the thumbnail from the 2nd popeye stays on top of the enlarged image.

    This happens every time in FF3.0.5 (Win). In Safari 3 (Win), you have to enlarge the 2nd image, then click the 1st thumbnail before it triggers the issue.

    IE6 & 7, Opera 9 and FF 3.0.5 (Linux/Ubuntu) all work properly.

    Any ideas?

  35. Looks great, but its too buugy to me. IneternetExploter is used by too much people, so i cant use this plugin at my website! And then there are some smaller bugs (see #85)

    Not perfect at all, but maybee you will work on?

  36. First off, thanks for this ‘alternative’

    I would like to play devil’s advocate a bit. I will enjoy utilizing this, but I don’t believe Lightbox, or it’s many clones, is/are a ‘bad’ thing.
    I don’t think Lightbox is a distraction our users (should Lightbox actually be needed) but rather it provides a way for the user to focus on the image/artwork for which the developer decided Lightbox was the best solution to portray.
    It provides a venue similar to a museum or art-gallery’s layout of pictures in clean environs.

    Again, thanks for your script(s) and your continued support of this valuable alternative.

  37. I think this is a great solution. Thanks!
    Is there a way to use a flickr stream instead of an ? I know flickr uses an but I’m not sure how to incorporate it.
    Thanks again!

  38. you don’t like internet explorer 6 do you?
    style 2 for popeye and your blog too, they don’t seem to be ok if using IE6.
    Know what? You are right!
    (great work, I’m using it and I will credit you)
    bye

  39. Hello. Lovely work but I was wondering if anyone knows how to force images to show at a given size. I don’t have the luxury of having a thumbnail version of each image and seeing as the script actually shows the thumbs as a background image, my images end up too big for the stage!

  40. Hi,

    It looks real great, exactly what I need for the website I’m building…..
    But….
    I also get this weird ‘condensed’ view. In Safari 3.2.1. en FF 3.0.6. ( I use a mac, but can view the example correct… so don’t see what the issue is …)

    I tried to grab any solutions for this form the forum but can’t find them. Does anyone has found a solution to this?

    I do see some ‘script’ examples, that I could change but I’m not sure where and for what purpose…. :S Can’t distinguish this from the posts..

    anybody any insights on this?
    (see the link of work in progress attached)

  42. @everyone: I’m sorry I still haven’t come up with a bugfix. It was planed for End of Jan, but I was too busy and still am. Hope to get some work onpopeye done in March…

    @filipo: Right on! On my personal site, I really don’t care about those 0,6% still using IE6.

  43. Hey guys, if you’re still getting the small thumbnail issue on page refresh/reload, add some rules to your CSS to force the widths into displaying correctly (change the ones below to the width & height you require.

    .popeye-stage {
    height:363px !important;
    width:598px !important;
    }

    same goes for .popeye-tools and .popeye-cap.

    Hope it helps,
    -Jordan

  44. You indicate explicitly to use the latest version of jquery. My experience is that it works fine in 1.2.6, but not in the latest (1.3.2). Can you confirm?

    Also some IE 7 quirks, but it’s a great piece of work, thanks for sharing!
    Danke Schön!

  45. I’ve read comments and it seems a feature request I’m thinking about is not in the list :
    When the image is in full size, it would be great to be able to naviguate in zoom state images with arrow key. The only way I found to view all images in full size is to click on the image ( zoom ), click another time ( unzoom ), click on the arrow right ( image change ), click on image again (zoom), etc… Maybe I haven’t found the way to achieve this. If such a feature doesn’t exists I realy think it would be great.

  46. I have been trying out lots of different photo plugins recently. This is definitely one of my favourites so far – I like the image being displayed within the page.

  47. Does someone know if it is possible to display a short text under the enlarged images and how to do it?

  48. Hello guys, first of all, congrats for this plugin, its great.
    Im trying to validate it according to w3c rules but the images has no ‘/>’ close tag, just the ‘>’, does any one know how to insert it?
    thx

  49. hi
    great plugin, thanks

    i made 2 changes for it: added ability to move next/prev large image, not only preview. also fixed bug, when in ie we cant enlarge same image twice.

    if need it – primpil@gmail.com
    regards

  50. possible to work with flickr ?
    i mean, i retrieve my images from flickr, then load it to popeye.

    i tried using jquery.flickr-1.0.js but cant get it to work.