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.

Examples

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).

$('a').butterfly();

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.

Download

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.

Package

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

Changelog

  • 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: https://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 Comments

11 Responses to "Butterfly lightbox"

  • By Dan Green February 4, 2014 - 4:32 am

    Im using jquery 1.10.2 and it seems like Im having compatibility issues. Is this only designed to run in 1.8 or lower?

  • By Andrew Ramsden March 15, 2014 - 3:56 pm

    Hi Dan,

    Yes this script is currently tested up to jQuery 1.8.3.

    A compatible version may be released in future. Until then, I recommend using the jQuery Migrate plugin.

    Good luck!

  • By Dan Green March 31, 2014 - 1:12 am

    Thanks Andrew. One additional question: When I close the lightbox, the page jumps to the top. (although, the link that launches the lightbox is still focused) This did not happen on previous versions of butterfly that I have implemented in the past. I noticed this behavior on the demo too. Thoughts?

  • By Mario May 17, 2014 - 5:31 am

    Great script I like it because it is the only accessible lightbox i’ve fond. I have a question, is it possible to have the lightbox load up on page load so that it is the first thing a person sees?

    Thanks

  • By Andrew Ramsden May 17, 2014 - 6:56 pm

    Hi Mario,

    You could try something like the following…

    $(function() {
    $('#link-id').click();
}

    This will simulate a click on the lightbox link on page load.

    Let me know how you go.

  • By Mario May 23, 2014 - 3:24 am

    Thanks for the response, didn’t have much luck, i’ll play around with it a bit more as I probably did something wrong.

  • By Mario May 23, 2014 - 3:31 am

    I spoke too soon, i ave it working, thanks for your help and the great accessible lightbox. Have you ever thought about turning this into a wordpress plugin?

  • By Rani March 18, 2015 - 8:12 pm

    Hi
    I’m trying to migrate it into wordpress.
    I’m working with jquery version 1.11.1. The plugin doesn’t work.
    What should I change?
    Thanks
    Rani

  • By Andrew Ramsden April 9, 2015 - 5:08 pm

    Hi Rani, I’ve only tested with up to jQuery 1.8.3 (it’s been a while since it’s had much attention). What error are you getting?

  • By Neil July 30, 2015 - 7:42 pm

    Hello – thanks for the great plugin.

    I am having the same problem as Dan. “When I close the lightbox, the page jumps to the top.” Is there anything I can do to prevent this?

    Thanks!

  • By Lightboxes Don't Have To Be Inaccessible - Customer Servant Consultancy December 22, 2015 - 10:57 am

    […] Why yes, you can haz accessible lightboxes. And with just a bit of work, this could also be used in WordPress things. It’s GPL, so go have fun. […]

Leave a reply