Felix Nagel edited this page Sep 7, 2013 · 42 revisions
Clone this wiki locally

Yet another lighbox application as you might know it by Lokesh Dhakar. This one displays pictures in a single or gallery mode and comes with a lot of features and accessibility tweaks.



Real-Life examples

Contact me to add your project here.

Functionality features

  • all Strings editable
  • gallery functionality
  • configurable “darken background” functionality
  • set position for lightbox by auto, x and y coords or offset to mouse
  • disabled if screen is too small
  • set animation speed
  • standard jQuery widget methods: disable, enable, destroy

File size of the minified version is less than 11 KB.

Accessibility features

  • full browser history and title support via jQuerry Address
  • keyboard support (ESC, arrow keys, Home, End)
  • fully scalable (with text size)
  • ARIA Live-Regions
  • ARIA relations


A very short documentation. Please take a look in the demo source-code.


Add th JS files like in the demo and prepare a set of images. There’s no need for thumbs but there must be a link tag. You should edit altText and descText options to fit your needs.

Single Lightbox:


Gallery Lightbox

jQuery 1.3.x and UI 1.7.x (legacy branch)

	imageArray: []

Just add a empty array to option imageArray to activate gallery mode.

jQuery 1.4.x and UI 1.8.x (master branch)

As I did some changes for the new jQuery versions, there a small changes when using gallery mode.

	imageArray: "a.your-css-class"

“.image-wrapper” could be any wrapping element (even “body”), but please dont reuse wrappers multiple times.


Option Type Description
imageArray Array or false modes: single and gallery view (defined with an empty imageArray: [])
altText string which attribute (within the image) set as alt attribute
descText string which attribute (within the image) set as description text
prevText string / function use return value to pass a string ($(this) is your a tag)
nextText string / function see above or see the demo
titleText function _title_Text of the lightbox
pictureText string PICTURE 1 of 10”
ofText string “Picture 1 OF 10”
closeText string close element
pos string position of the lightbox, possible values: auto, offset, or [x,y]
autoHeight number only if “pos: auto” is set: true for center vertically or a number for fixed margin to top
offsetX number if pos:“offset” its the distance between lightbox and mouse-click position
offsetY number see above
disableWidth number deactivate widget if screen is smaller than
disableHeight number see above
useDimmer boolean activate or deactivate dimmer
animationSpeed number or string in milliseconds or jQuery keywords aka “slow”, “fast”
zIndex number z-index for overlay elements
dimmerOpacity number (0-1) opacity of the dimmer div
background string color in HTML notation [legacy]
opacity number decimal between 1-0 [legacy]
makeHover boolean deactivate hover events for images
em number multiplication for relative width (em) calculation, could be turned of by setting option em to false
jqAddress.enable boolean enable browser history support
jqAddress.title.enable boolean enable title change
jqAddress.title.split string set delimiter string

You need to add the add the jQuery Address file, if you like to use browser history support. jQuery Address support is currently only available in master branch (jQuery 1.4, UI 1.8).

em Calculation

We need to convert size in pixels to relative em units (which are based on a text size) if we like text-scalable lightbox pop-ups. Default settings is 0.0568182 for 16px as body font size and 1.1em as defined by css for element #ui-lightbox-wrapper.
Its body font size in em / font-size in em of the lightbox-wrapper = options.em
0.0625 / 1.1 = 0.0568182

body font size in px body font size in em
16px 0.0625000em
15px 0.0666667em
14px 0.0714286em

Try emCalc to calculate your own.


Events fired after function has finished.

  • onShow
  • onChangePicture
  • onClose
  • onPrev
  • onNext


The method startGallery should have the event as a parameter. It’s possible to pass a index (int) as secod parameter. See demo source-code.

  • startGallery (event[, index])
  • close
  • next
  • prev
  • enable
  • disable
  • destroy

Necessary CSS

These styles are necessary if the widget should work correctly.

/* Lightbox Styles
#ui-lightbox-wrapper {
	display: none;
	position: absolute;
	width: 20em;
	height: auto;
#ui-lightbox-image {
	height: 10em;
	margin: 1em 0 0 0;
	background: url(ajax-loader.gif) no-repeat center center;
#ui-lightbox-image img{
	display: none;


Trigger one lightbox picture with multiple links

All we need do is to trigger the click event for the “default” link which triggers the lightbox. Use following code snippet to open same lightbox with multiple links:

$("myGallery").find(".someDiv a").click(function() {
	return false;

This text is licensed under a Creative Commons Attribution-Share Alike 3.0 Unported Licence.