Butterfly lightbox

Why create yet another lightbox clone? Because the butterfly lightbox widget provides a robust, flexible and fully accessible lightbox soution. This solution accounts for window and text resizing, keyboard accessibility and controls focus appropriately for users of assistive technologies (see lightbox accessibility for more detail).

Butterfly has been tested and works in Internet Explorer 7–9, Safari 5, Chrome 11, Opera 11 and Firefox 3–4.


Place the following code in the <head> of your XHTML document.

Note: For best performance, it is recommended that you combine all the JavaScript files below into a single minified file.

<script type="text/javascript" src="jquery-1.6.1.js"></script>
<script type="text/javascript" src="jquery.resize-events.js"></script>
<script type="text/javascript" src="jquery.pxToEm.js"></script><!-- optional script if you wish to specify dimensions in em units -->
<script type="text/javascript" src="jquery.butterfly.js"></script>
<link rel="stylesheet" type="text/css" href="butterfly.css" />

The plugin can act on any link in the <body> of your document, for example:

<p><a href="butterfly.jpg">A beautiful butterfly</a></p>

The plugin needs to be initialised after the link markup has been parsed (once the DOM is ready is soon enough).


There are various options that can be passed on initialisation.

This will result in a link that opens the butterfly image in a lightbox layer above the main page content.

Working example

A complete demonstration of the butterfly plugin is available.


butterfly is licensed under the The GNU General Public License (GPL), by downloading it you are agreeing to abide by the terms of that license.


Download the complete butterfly 0.13 example package (.zip)

Individual files

Plugin options

The following options can be can be passed on initialisation of the plugin:

options = {
	contentDefaultWidth: null, // For content (can be em, % or px) - null default means 50em if pxToEm is available or 700px otherwise (a good line length for legibility)
	contentDefaultHeight: '100%', // For content (can be em, % or px)
	mediaMaxWidth: '100%', // For images (can be em, % or px)
	mediaMaxHeight: '100%', // For images (can be em, % or px)
	treatAsMedia: false, // Set to true for content to be resized as if it's media (good for video content)
	lightBoxMargin: null, // Margin around screen (can be em, % or px) - null default == 2em if pxToEm is available or 20px otherwise
	animateResize: true,
	animationSpeed: 150,
	useIframe: 'autodetect', // load contents in an iframe (good for cross-domain URLs). Options are: 'autodetect' (will load iframe for external URLs), true (will load in an iframe). false (will atempt to load with ajax).
	collapseHeightWhenPossible: true, // When content is shorter than available height, collapse height of lightbox
	reuseFragment: false, // When using a fragment from the same page as the link, reuse the same DOM nodes (persisting their state) or clone a new copy?
	closeButton: false, // Should we have a close button?
	closeButtonImage: '', // Set to the path of your close button image
	closeButtonCorner: 'tl', // Top left 'tl' or top right 'tr' or bottom left (bl) or bottom right (br) - top left is the most intuitive option that doesn't overlap scrollabrs
	clickOverlayCloses: true, // Will clicking the overlay layer (the dark tinted area) close the lightbox?
	preloadLoadingImage: '', // Specify an image path here and it will be preloaded
	preloadGalleryControlsSprite: '', // Specify an image path here and it will be preloaded
	galleryControlWidth: 49, // width of each control (default based on sprite that ships with butterfly)
	galleryControlHeight: 85, // height of each control (default based on sprite that ships with butterfly)
	galleryMode: 'rel', // Allow navigation between lightboxed images? Options are: rel (all links that have the same 'rel' attribute), 'container' (all links within the one container), 'all' (all linked images), or nothing '' (don't use galleries)
	galleryContainers: '', // CSS selectors specifying elements that contain linked images to form discrete galleries. e.g: '.gallery-pets, #gallery-flowers'
	galleryLoops: false, // When you reach the end of the gallery, should 'next' take you back to the begining? (and vice versa)
	captionMode: 'title', // Whether to use captions, and if so, where to grab the caption text from? Options are: 'title' (the title attribute of the link), 'text' (any text within the link, including image alt text), or nothing '' (don't display captions)
	preloadNextGalleryImage: true, // Should the next lightbox be preloaded if it's an image?
	zoomFromClicked: false, // Experimental
	callbackPreOpen: null, // Six callback functions can be defined that will be called at various points in the opening, closing and resizing of lightboxes
	callbackPreResize: null,
	callbackPostResize: null,
	callbackPostOpen: null,
	callbackPreClose: null,
	callbackPostClose: null,
	treatAsImage: false // If set to true, will treat all links as image links (overriding automatic type detection).


  • 0.1 Initial implementation.
  • 0.2: Support for window resizing added.
  • 0.3: Support added for callback functions (open/close/resize pre and post events). Error handling added for when lightbox target resource doesn’t exist.
  • 0.4: Accessibility features added (controlling focus for user initiated lightboxes, keyboard support) – as per: http://irama.org/web/dhtml/lightbox/#accessibility
  • 0.5: Bug fixes for webkit. Blocked IE6 (no LB for them). Basic caption support (thanks to Ray Latchmanan). Gallery support.
  • 0.6: ARIA style keyboard support for navigating through galleries. Keyboard access now trapped in lightbox while lightbox is open. Support for preloading next image in galleries.
  • 0.7: Captions can be configured to come from link title attribute, link text (including any img alt text within), or not be displayed at all.
  • 0.8: Added ability to load pages in an iFrame (kicks in automatically for external-domain URLs).
  • 0.9: Support restored for IE6 (all thanks to the perseverance of github.com/bboyle – he has more patience than I). Added support for back button (through jquery.history.js)
  • 0.10: Set default close icon; fixing issues reported by jslint; minor jquery optimisations (thanks to Ben Boyle)
  • 0.11: Fix for jQuery 1.8 compatibility issue (thanks to Roger Kowallis for raising the issue)
  • 0.12: Fix for captions extending outside lightbox (thanks to Roger Kowallis)
  • 0.13: Added option to treat links as image links (overriding automatic type detection). Handy for image URLs that don’t have an image file extension (like Google Charts API URLs)

Posted in

11 Responses to "Butterfly lightbox"

Leave a reply