Create a Dojo Lightbox with dojox.image.Lightbox

By on  

One of the reasons I love the Dojo Toolkit is that it seems to have everything.  No scouring for a plugin from this site and then another plugin from that site to build my application.  Buried within the expansive dojox namespace of Dojo is dojox.image.  dojox.image is host to many common UI plugins, the most popular being dojox.image.Lightbox, a great solution if you're looking to create a reliable, elegant Lightbox with Dojo.  Let me show you how use dojox.image.Lightbox in your next web application!

dojox.image.Lightbox and dojox.image.LightboxDialog Features

The dojox.image.Lightbox resource has many cool features:

  • Integrated theming and images
  • Keyboard accessible
  • Resizes when the viewport changes
  • Flexible with numerous options
  • Declarative or Programmatic instance creation
  • Works with Dojo data stores

Let me show you just how easy it is to use Dojo's Lightbox solution!


dojox.image.Lightbox doesn't require any of the Dijit themes but does require its own CSS file:

<style type="text/css">
	/* bring in the lightbox CSS */
	@import "http://ajax.googleapis.com/ajax/libs/dojo/1.6/dojox/image/resources/Lightbox.css";

All of the imagery required comes via the CSS file -- no need to add your own styles.

The HTML and JavaScript

The first step in using any Dojo resources is adding a SCRIPT tag with a path to Dojo within the page and requiring the desired Dojo Toolkit resources:

<script src="http://ajax.googleapis.com/ajax/libs/dojo/1.6/dojo/dojo.xd.js"></script>
<script type="text/javascript">
	// Request dependencies

The dojox.image.Lightbox resource can be used declaratively (with HTML) or programmatically (with JavaScript).  If you plan to use declarative widget creation, you'll need to set the djConfig object's parseOnLoad property to true before loading Dojo:

// Parse the page upon load
djConfig = { parseOnLoad: true };

With parseOnLoad in place, you can add links to the page with the data-dojo-type attribute set to dojox.image.Lightbox and instance-specific options within the data-dojo-props attribute.  Here's a sample:

<div id="imageHolder">
	<a href="slideshow/cricci1.jpg" data-dojo-type="dojox.image.Lightbox" data-dojo-props="group:'GoddessPics',title:'Christina Ricci',href:'slideshow/cricci1.jpg'"><img src="slideshow/cricci1.jpg" alt="Christina Ricci" /></a>
	<a href="slideshow/cricci2.jpg" data-dojo-type="dojox.image.Lightbox" data-dojo-props="group:'GoddessPics',title:'Christina Ricci',href:'slideshow/cricci2.jpg'"><img src="slideshow/cricci2.jpg" alt="Christina Ricci" /></a>
	<a href="slideshow/cricci3.jpg" data-dojo-type="dojox.image.Lightbox" data-dojo-props="group:'GoddessPics',title:'Christina Ricci',href:'slideshow/cricci3.jpg'"><img src="slideshow/cricci3.jpg" alt="Christina Ricci" /></a>
	<a href="slideshow/cricci4.jpg" data-dojo-type="dojox.image.Lightbox" data-dojo-props="group:'GoddessPics',title:'Christina Ricci',href:'slideshow/cricci4.jpg'"><img src="slideshow/cricci4.jpg" alt="Christina Ricci" /></a>
	<a href="slideshow/cricci5.jpg" data-dojo-type="dojox.image.Lightbox" data-dojo-props="group:'GoddessPics',title:'Christina Ricci',href:'slideshow/cricci5.jpg'"><img src="slideshow/cricci5.jpg" alt="Christina Ricci" /></a>

Groups allow you to have images available within...groups... with next and previous buttons.  The title property provides a ...title... and the href property provides the content which should load within the lightbox. You may have any number of groups on the page.  That's all that's needed to create a simple Dojo Lightbox declaratively!

If you're looking to create your Lightbox programmatically, no problem -- that's easy too!  Add your images to the page the same way you did above, minus the data-dojo-type and data-dojo-props attributes, and instead use the following JavaScript code:

// When the DOM is ready and resources are loaded...
dojo.ready(function() {
	// Create an instance
	var lightbox = new dojox.image.Lightbox({ title:"Christina Ricci", group:"GoddessPics", href:"slideshow/cricci1.jpg" });
	// Start it up!

With your instance created, start adding more images:

// Add another image by using the lightbox's _attachedDialog method...
	title:"Christina Ricci 2", 
	group:"GoddessPics",  // Can be same group or different!

Regardless of declarative or programmatic implementation, you can show or hide the lightbox with the respective methods:

// Show the lightbox
// Hide the lightbox!

As you'd expect with any Dojo Toolkit resource, dojox.image.Lightbox provides the usual onShow, onHide, and other utility methods that are helpful in customizing the Lightbox usage.

dojox.image.Lightbox and dojox.image.LightboxDialog are great resources available within Dojo's "treasure chest", DojoX. Other classes within the dojox.image namespace include Gallery, Slideshow, and Magnifier. Look forward to tutorials about those soon!

Track.js Error Reporting

Upcoming Events

Recent Features

  • CSS @supports

    Feature detection via JavaScript is a client side best practice and for all the right reasons, but unfortunately that same functionality hasn't been available within CSS.  What we end up doing is repeating the same properties multiple times with each browser prefix.  Yuck.  Another thing we...

  • Create a CSS Flipping Animation

    CSS animations are a lot of fun; the beauty of them is that through many simple properties, you can create anything from an elegant fade in to a WTF-Pixar-would-be-proud effect. One CSS effect somewhere in between is the CSS flip effect, whereby there's...

Incredible Demos

  • MooTools&#8217; AutoCompleter Plugin

    One of the famous MooTools plugins is Harald Kirschner's AutoCompleter plugin. AutoCompleter takes a term input by the user and searches for matches -- an obviously help to the user. Here's how to make the most of Harald's great plugin. The XHTML All we...

  • Scroll IFRAMEs on iOS

    For the longest time, developers were frustrated by elements with overflow not being scrollable within the page of iOS Safari.  For my blog it was particularly frustrating because I display my demos in sandboxed IFRAMEs on top of the article itself, so as to not affect my site's...


  1. Quick note: WebKit has an outstanding issue the load event firing properly. The team is aware of the issue and looking to fix it:


  2. Jack

    This seems a bit odd, can you not just specify a parent element to assign the lightbox to the images within? Rather than adding them all separately? Or am I being an idiot?

    PS – loving all the Dojo stuff, as a pretty experienced jQuery dev, I’ve been looking into a new library andDojo is winning right now.

  3. Hi David, Great article again!.. .this is very amazing.

  4. Alex

    The resizing for viewport feature is particularly valuable. I haven’t found a good lightbox plugin for mootools which does this. Thanks!

  5. I understand the built-in aspect of this, but doesn’t Shadowbox.js do a better job? And when integrated with MooTools, the transitions are amazingly smooth. I was getting some perceived lag with the demo on this computer (XP Pro 2.6GHz Dual Core 2GB RAM, Integrated Graphics). And Shadowbox even has the option to integrate with Dojo (along with MooTools, jQuery, Prototype, YUI and Ext). So far, I haven’t had a situation where Shadowbox wasn’t perfect for the job.

    But maybe I’m just being contrary.

  6. Petah

    Not the best lightbox effect ive seen. It was jumpy and couldn’t click next/prev on the image itself. Also it faded to white between images.

  7. DRoss

    I have to click the tiny arrows at the bottom to switch between images? Really?

  8. Ok first off you can’t go wrong with Christina Ricci. However, I agree with Petah … It’s too jumpy … I think a small adjustment will make it better … Thanks for the share.

  9. jun.p


    thanks for your lightbox tutorial

    But I discovered something that when I put menubar with lightbox, it has some issues. the lightbox doesnt work.

    try it please with your side, because I cannot make it work.

    please help and thanks

  10. Jerrhann

    Thank you for sharing! However, code does not work. Calls to the lightbox.show(); return error: “Lightbox is not defined”

Wrap your code in <pre class="{language}"></pre> tags, link to a GitHub gist, JSFiddle fiddle, or CodePen pen to embed!

Recently on David Walsh Blog

  • Intercept HTTP Requests with Node.js nock

    Unit testing external APIs is difficult no matter what language you do it in.  Hell, working with any external API is scary, if only because you have zero control of networking issues, API changes, and a host of other issues.  But if you do create a service...

  • Introducing Frontend Masters (with Giveaway)

    Hey DWB readers, I'm super happy to sponsor this blog. I've been a long-time reader and fan, since back when David wrote about JavaScript and MooTools back in 2007. ;-) We are in one of the fastest changing, evolving, most lively communities on earth: JavaScript and front-end web...

  • Get Node.js Command Line Arguments with yargs

    Using command line arguments within Node.js apps is par for the course, especially when you're like me and you use JavaScript to code tasks (instead of bash scripts).  Node.js provides process.argv but that doesn't provide a key: value object like you'd expect: Bleh.  If you want to work with a...

  • OâReilly Velocity Conference â New York

    My favorite front-end conference has always been O'Reilly's Velocity Conference because the conference series has focused on one of the most undervalued parts of client side coding:  speed.  So often we're so excited that our JavaScript works that we forget that speed, efficiency, and performance are just as important. The next Velocity...

  • Free Download: Font Bundle Featuring 17 Incredible Typefaces

    The only thing we love more than a good font, is a good free font. So we’ve combed the Web for some of our favorite free fonts, and gathered them here in a single download. You’ll find a variety of useful typefaces, from highly geometric designs...