YUI Based Lightbox – Final

Download Latest Source Code | change log
Download YUI
Thumbnail-less demonstration
Thumbnail-enabled demonstration
Create your own

My previous YUI implementation of the lightbox, which was released for beta evaluation, now has nearly gone gold. This page will be devoted for upcoming updates and bug fixes. So if you've found any bugs, feel free to report them in the comment section of this post.

Also, I would like to thank many who reported bugs and gave feedbacks after the release of previous image lightbox. As many have requested, I implemented navigation for the new lightbox. In addition to the navigation, numerous new features have been added and bugs have been fixed.


Table of Contents

What's New

The most significant change in this version of the lightbox is that image thumbnails are no longer required for creating lightbox instance. That implies that you can create an image gallery without the presence of image thumbnails. The more exciting aspect of this new feature is that you can virtually grab any image from the internet and include it in your gallery. Test-drive this new feature.

Below is the detailed list:

  • Ability to view full size and auto-fit version of the image
  • Settings for changing background mask opacity and color
  • keyboard shortcuts
  • Tooltip panel for displaying extra information
  • Navigation control toolbar
  • Image transition effect
  • External stylesheet for styling

Bug Fixes

  • Fixed image goes outside of viewport bug
  • Removed extra scrollbar when the image can be fit into the viewport

The lightbox has been tested in Firefox, IE 7, Opera 9.21.


Download the latest lightbox source and unpack it to your project directory.

Include the following files to your page:

If you prefer to serve above files locally, you can download YUI from here.

JavaScript Code

First, create a data source object to represent the photo gallery:

If you need to add more images to the gallery, simply add more tuples to the data source. For each tuples, attributes title and text are optional.

After data source object has been created, you can instantiate an instance of the lightbox:

To show the lightbox, simply call

That's all.

Putting Everything Together

Optional Settings

If you are not happy with the default settings that bundled with the lightbox, feel free to modify them at your will. Here's a list of settings you can modify:

NameDefault ValueDescription
idtcc_showImgPanelSet HTML ID attribute of the lightbox. Used only when create multiple instances of lightbox
maskOpacitySet by YUIOpacity of the background mask
maskBgColorSet by YUIColor of the background mask
modaltrueSet this to true will block user inputs to other elements below the mask
hasThumbnailstrueIf set to true, the lightbox will attach click event to images which IDs are specified in the data source
ctrlVisibletrueVisibility of the control panel
ctrlOpacity.5Control panel's opacity
effecttrueFade in effect between images
effectDuration1Effect duration in second
tooltiptrueVisibility of the tooltip
tooltipOpacity.9Opacity of the tooltip


Styling the Lightbox

You can style the lightbox by editing lightbox.css, which can be found under the lightbox distribution. If you are a CSS guru, things would be self-explanatory.

Image Preloading

Since RC2, you are given the ability to preload images before bringing up the lightbox. Preloading images is easy, simple call preloadAll() method on the lightbox instance:

If you want to be notified during the preloading process, you can subscribe to the following events:

  • preloadStartEvent - fired before preloading of single image
  • preloadCompleteEvent - fired after preloading of single image
  • preloadCompleteEvent - fired when all images have been preloaded

You don't need to to subscribe to all them, just the ones you are interested at. Here's a code snip on how:

Inside of the event handler, you can access information about current image through the second argument of the handler:

For preloadStartEvent and preloadCompleteEvent, this argument is an associative array with two attributes:
imageId: the image ID you specified in the data source
ds: the data source tuple associated with this image ID

For preloadCompleteEvent, this argument is the number of images that preloaded.

You can find more information on YUI's event framework here. I've also compiled a list of YUI's event handlers.

Change Log

lightbox-final-RC4.zip (4/19/2008)
Bug Fix: When creating multiple instances of the lightbox, the toolbar of all instances use the same ID.
RC4 forces each instance of the lightbox uses a unique ID for its toolbar.
lightbox-final-RC3.zip (1/7/2008)
Bug Fix: Updated help file. Removed Ctrl + Click shortcut in help file, replaced by Space bar
lightbox-final-RC2.zip (1/4/2008)
Bug Fix: Change variable name "pagepageScrollTopValue" to "pageScrollTopValue"
Enhancement: Added preload all images feature
lightbox-final-RC1.zip (1/1/2008)
Initial release

Thank you for visiting and Happy New Year!

Related Links

43 Comments YUI Based Lightbox – Final

  1. Daniel Jalkut

    Thanks a lot for making this available. I really like the aesthetics you're going for a lot more than in some other solutions I've seen.

    You may be pleased to know that it seems to work pretty well in Safari. I found a bug however, that was only exposed after trying it with the latest and greatest WebKit from Apple. Am I right in assuming that every instance of "pagepage" in the script should actually be "page" ? I did this global replace and things were a lot better.

    One thing I'd like to be able to do is to preload images before showing any UI. In other words I'd like to be able to have the images loading in the background before the user clicks any thumbnail. Is this possible?

    Thanks again,

  2. Cuong

    Thank you for your generous support.

    Indeed the variable name "pagepage" is a bug. I wasn't aware of how it got into the source, probably due to some mindless copy and paste.

    I changed the "pagepage" to "page", as well updated the source code for background preloading. Please check updated documentation for more detail. Thanks.

  3. Dennison Uy - Graphic Designer

    Impressive work. My only issue with this is that it is a bit heavy and could have been implemented more elegantly with pure DOM manipulation so I really do not see its advantage over something lightweight like lightbox JS. Also, I couldn't get the image resizing to work, no matter how many times I try to do control click

  4. Cuong


    The manual is a little bit outdated, the keyboard shortcut for resizing is Space Bar/Up Arrow. I'll update the manual/screenshots soon.

    Speaking of advantages, the biggest one is the ability to display full size and best fit version of a image, which is my initial motivation of making this lightbox. On top of that, I added thumbnail-less feature. With this feature, you can easily create a photo gallery by feeding the lightbox a image source. Test it here

    The end product of this is similar to those XML flash gallery, but the difference is without security restriction. So you can grab some random images from the internet and create a slide show from them. Also this lightbox is highly configurable. For each instance of the lightbox, you can change many attributes such as maskBgColor on the fly.

    I am not saying this is lightbox is superior than others, but just pointing out the unique features. Hopefully it helps.

  5. Ryan

    This looks great, but I'm looking for help with one more feature. I'd like to use your code in a widget that's hosted within an iframe on a page I don't fully control. I'd like the image to fill the entire window rather than only the iframe document. What kind of changes would be necessary? I thought just turning all the document.createElement methods to parent.document.createElement would do the trick, but no luck.

  6. Edith

    Hi, I was exactly looking for a lightbox like yours, working without thumbnails. But unfortunately I can't make it work.


    lightbox is not defined
    onclick(click clientX=0, clientY=0)

    I've used exactly your code and correctly included
    Lightbox-min.js and lightbox.css.

    Can you please give me a hint what I'm missing??
    Thank you so much!

  7. Cuong


    Two things:
    1) Move the variable lightbox out of the init function, so it can be seen by rest of the code.

    2) Instead of Lightbox.show(), try lightbox.show().


  8. Drew Freyling

    Nice work guys. I reckon this deserves its own project on Google Code or the like for future updates.

    For those using YUI's Font package, you can modify the following lines of the stylesheet to conform the font size percentages and predefined font degradation path:


    IM trying to use your lighbox-mini browser
    its working when i am using a page on my server
    my question is --- how can i call the light box mini-browser
    when i am on any page (not in my server), so i will have the backgrouon page = the web site page not mine and in the ligth box browser - my page -- that i already figer how to change the src of the light box
    how it will work ?
    i am calling a js file that located in my web site (i click a favorit link that open the js file,
    then in the js file i am loading the yui js file and calling the mini-browser

    at this point - its faild calling the mini-browser
    , i tryied to call different yui function like the 'hello world msg' and it working

    please let me know what i am doing wrong

    thank you.

  10. Pingback: Web 2.o Round up Modal Window Lightbox Effect Library

  11. Pingback: Lightbox ?ffnen vor Seitenladen - Javascript & Ajax @ tutorials.de: Forum, Tutorial, Anleitung, Schulung & Hilfe

  12. Daniel Gardner

    This is a great gallery! Thanks for making it available.

    I've run into a sad bug. I set up a gallery and downloaded YUI today and Chrome and FF read it perfectly but my IE7 won't touch it. Only shows thumbnails, but doesn't offer to click them (i.e. the thumbnails aren't clickable.)

    However, the demo here at codecentral works fine on my IE7. Any help guys? Thanks!

    here's where I'm using it:

  13. Cuong

    Hi Daniel, sorry for the delayed response. I have been away from my blog for away. After talking look at your code, I found a the code which causes the problem.

    In the last line of your datasource, you need to remove the comma. So change this line from


    IE's parser has problem parsing this code. I made the same mistake way back ago, it's really annoying.

  14. Pingback: 56 ?AJAX??????(Galleries, Slideshows and Lightboxes) | ???????

  15. Nata

    Thank you for the great code that is easy to use without knowing a lot of details about YUI.
    I was able to make it working the way I want, except positioning the image to the different place (slightly to the righ, but ideally to insert it inside existing element) on the screen. Can you help please pointing me to the function that I can change it.

  16. Pingback: 56 Scripts For Galleries, Slideshows and Lightboxes « LanceZhang’s Blog

  17. Pingback: pligg.com

  18. Levi

    Hi Cuong

    I like your code very much and decided to give it a try in my project.

    If I would like to set "onclick='lightbox.show();'" for my hyperlink text field (ie. without the imageID, as the hyperlink text itself is the image file name. eg. ABC123.jpg),
    how do I write the dataSource?

    I hear from you soon. :)

    var dataSource = {
    image1:{url:"photos/1.jpg", title:"hi", text: "shot"},
    image2:{url:"photos/2.jpg", title: "tes"}
    //...and so on

  19. Levi


    One more question, I was trying to include the line

    into my page header in (ASP Maker) project where the js file is placed in the lightbox folder in my project folder. I got IE error that "Object doesn't support this property or method".

    It works fine while I tried to include JQuery's js files.

    Did I miss something?

    I hear form you soon.

  20. Levi

    opps... the line is missing...

    script type="text/javascript" src="lightbox/Lightbox-min.js"></script

    (with opening & closing angle brackets)

  21. Ed

    Can't get the maskOpacity to work with IE7. Firefox and Safari work fine. URL is http://dev.ilikesongs.com/SES Then pick photos.

    lightbox = new YAHOO.com.thecodecentral.Lightbox(dataSource, {
    id: 'showtcc',
    maskOpacity: .8,
    maskBgColor: '#000',
    modal: true,
    hasThumbnails: true,
    ctrlVisible: true,
    ctrlOpacity: .5,
    effect: true,
    effectDuration: 1,
    tooltip: true,
    tooltipOpacity: .9

  22. Michael Newton

    I'm disappointed that this doesn't work without Javascript enabled in the browser. All the thumbnail images should be links to the fullsize image, in case there is no Javascript available.

    Other than that it's a good job, but I'll have to fix the lack of graceful degradation before I can use it in my code.

  23. matt

    This script seems to break on-page navigation. For example, if page foo.html loads Lightbox-min.js, any link to a named anchor on that page will instead show the top of the page.

    For example: example.com/foo.html#bottom

    would show the top of foo.html even if there's an anchor named "bottom" near the bottom of the page.

    I can stop this behavior by removing the script tag for Lightbox-min.js

    Note: even if my code doesn't call any lightbox functions, this scrolling-to-top behavior still occurs.

    Is anyone else seeing this? Is there a fix?

  24. YOzefff

    @Michael Newton

    That IS possible ;-)

    for example


    click the thumbnail

    This script is great. Just put the ID on the img tag. Now you can make an A tag and a IMG tag inside. Just make sure the A tag has a onclick that returns false. And ofcourse the href points to your source image and the src points to your thumbnail. You still need to specify the thumbnail in the datasource.

  25. Bill Studer

    Great work on the YUI Lightbox.

    One small problem I found:

    I'm using a few other YUI components, including Yui Menu. However, I'm not using the Menu's default Sam skin, and I do not include class="yui-skin-sam" in the body tag, only in the div surrounding the Lightbox.

    Anyway, when I close a Lightbox, the script is somehow applying the .yui-skin-sam class and its styling to my Menu's custom skin.

    There is probably a better way to fix this, but I found the easiest way was just to remove the css file:
    /YUI_VERSION/build/assets/skins/sam/skin.css. This file actually contains yui-skin-sam styles for every yui component in the library. The only style Lightbox needs, however, is Yui Container, which is in the file

  26. YOzefff

    Nice script!

    Got a question .. is it possibile to dock the control bar directly under the image?

  27. YOzefff

    Hi nice work ... Used your script a couple of times .. but I do have some comments ..

    Its seems your script breaks down the PrototypeJS framework. I use PrototypeJS a lot (also with YUI).

    So I've checked out your source and I noticed this line:

    var $ = YAHOO.util.Dom.get;

    Any PrototypeJS programmer knows $ is used within PrototypeJS :( ...

    Could you rename your $ vars (I'm also talking about the $E var).

    I altered the code something like

    var $Evt = YAHOO.util.Event;
    var $get = YAHOO.util.Dom.get;

    as a hack ;-)

    Keep upt the good work.


  28. YOzefff

    Hi nice work ... Used your script a couple of times .. but I do have some comments ..

    Its seems your script breaks down the PrototypeJS framework. I use PrototypeJS a lot (also with YUI).

    So I've checked out your source and I noticed this line:

    var $ = YAHOO.util.Dom.get;

    Any PrototypeJS programmer knows $ is used within PrototypeJS :( ...

    Could you rename your $ vars (I'm also talking about the $E var).

    I altered the code something like

    var $Evt = YAHOO.util.Event;
    var $get = YAHOO.util.Dom.get;

    as a hack ;-) But I was hoping you could make a permanent version.

    Keep upt the good work.


  29. tworzenie-stron-www

    Komputer jest jednym z powodu ważniejszych wynalazków dwudziestego wieku. Jego możliwości są praktycznie nieograniczone tudzież ciągle się zwiększają. Kiedyś komputery zajmowały dobry pokój. Były ogromne, a ich szybkość działania pozostawiała dużo aż do życzenia. Można było na nich wprowadzać w życie zaledwie proste rachunki, azali obrabiać nieskomplikowane teksty. Obecnie komputery są właśnie zaawansowane, że nie jest nam obce zamieszczanie zdjęć, azaliż filmów do wnętrza Internecie. sieć z komputerem tworzą zgrane węzeł kolejowy a to podobieństwo zrewolucjonizowało kula ziemska informatyki. Na przypadek wytwarzanie stron www stało się owszem proste, że z powodu każdego miejsca na Ziemi, dokąd jest jeno komp z powodu łączem internetowym możemy przekazać aż do sieci stworzoną przy użyciu nas stronę internetową. Gdyby produkowanie stron www nie było właśnie powszechne i proste, owo prywatni użytkownicy negacja logiczna mogliby się wydzielać według innymi własną wiedzą oraz doświadczeniem. Nie powstałyby blogi tematyczne ze zdjęciami od ciekawych podróży, azali przepisami kulinarnymi. Na wesołość wytwarzanie stron www wypada do prostych czynności.

  30. Pingback: jQuery插件收藏

Comments are closed.