ColorBox, A jQuery Lightbox

10/11/11 6:36 PM

Jack Moore Blog Archive RSS Twitter Github

ColorBox
A lightweight customizable lightbox plugin for jQuery 1.3+

View Demos
12345

Download
Current version: 1.3.18 ( Released under the MIT License | Github | Changelog ) Tested in: Firefox, Safari, Chrome, Internet Explorer 6, 7, 8, 9, Opera 11.

Features
Supports photos, grouping, slideshow, ajax, inline, and iframed content. Lightweight: 10KB of JavaScript (less than 5KBs gzipped). Appearance is controlled through CSS so it can be restyled. Can be extended with callbacks & event-hooks without altering the source files. Completely unobtrusive, options are set in the JS and require no changes to existing HTML. Preloads upcoming images in a photo group. Well vetted (ColorBox is one of the top 10 jQuery plugins, currently used on tens of thousands of websites).

Instructions & Help

The FAQ has instructions on asking for help, solutions to common problems, and how-to examples. First-time jQuery users can check out the ColorBox Beginner's Guide. Intermediate users can probably glean everything needed by view-source'ing the demo pages.

Usage
ColorBox accepts settings from an object of key/value pairs, and can be assigned to any HTML element.
// Format: $(selector).colorbox({key:value, key:value, key:value});

http://jacklmoore.com/colorbox/

Page 1 of 6

ColorBox, A jQuery Lightbox

10/11/11 6:36 PM

// Examples: // Image links displayed as a group $('a.gallery').colorbox({rel:'gal'}); // Ajax $('a#login').colorbox(); // Called directly, without assignment to an element: $.colorbox({href:"thankyou.html"}); // Called directly with HTML $.colorbox({html:"<h1>Welcome</h1>"}); // ColorBox can accept a function in place of a static value: $("a.gallery").colorbox({rel: 'gal', title: function(){ var url = $(this).attr('href'); return '<a href="' + url + '" target="_blank">Open In New Window</a>'; }});

Settings
Property transition speed Default Description "elastic" The transition type. Can be set to "elastic", "fade", or "none". 350 Sets the speed of the fade and elastic transitions, in milliseconds. This can be used as an alternative anchor URL or to associate a URL for non-anchor elements such as images or form buttons. false
$("h1").colorbox({href:"welcome.html"});

href

title

false

This can be used as an anchor title alternative for ColorBox. This can be used as an anchor rel alternative for ColorBox. This allows the user to group any combination of elements together for a gallery, or to override an existing rel so elements are not grouped together.
$("a.gallery").colorbox({rel:"group1"});

rel

false Note: The value can also be set to 'nofollow' to disable grouping. If true, and if maxWidth, maxHeight, innerWidth, innerHeight, width, or height have been defined, ColorBox will scale photos to fit within the those values. If false, ColorBox will hide scrollbars for overflowing content. This could be used on conjunction with the resize method (see below) for a smoother transition if you are appending content to an already open instance of ColorBox. The overlay opacity level. Range: 0 to 1. If true, ColorBox will immediately open. If true, focus will be returned when ColorBox exits to the element it was launched from.
Page 2 of 6

scalePhotos

true

scrolling opacity open returnFocus

true 0.85 false true

http://jacklmoore.com/colorbox/

ColorBox, A jQuery Lightbox

10/11/11 6:36 PM

fastIframe preloading overlayClose escKey arrowKey loop current previous next close data

true true true true true true "image {current} of {total}" "previous" "next" "close" false

If false, the loading graphic removal and onComplete event will be delayed until iframe's content has completely loaded. Allows for preloading of 'Next' and 'Previous' content in a group, after the current content has finished loading. Set to false to disable. If false, disables closing ColorBox by clicking on the background overlay. If false, will disable closing colorbox on 'esc' key press. If false, will disable the left and right arrow keys from navigating between the items in a group. If false, will disable the ability to loop back to the beginning of the group when on the last element. Text or HTML for the group counter while viewing a group. {current} and {total} are detected and replaced with actual numbers while ColorBox runs. Text or HTML for the previous button while viewing a group. Text or HTML for the next button while viewing a group. Text or HTML for the close button. The 'esc' key will also close ColorBox. For submitting GET or POST values through an ajax request. The data property will act exactly like jQuery's .load() data argument, as ColorBox uses .load() for ajax handling. If true, specifies that content should be displayed in an iFrame. If true, content from the current document can be displayed by passing the href property a jQuery selector, or jQuery object.

Content Type iframe false

inline

false

// Using a selector: $("#inline").colorbox({inline:true, href:"#myForm"}); // Using a jQuery object: var $form = $("#myForm"); $("#inline").colorbox({inline:true, href:$form});

For displaying a string of HTML or text. html false

$.colorbox({html:"<p>Hello</p>"});

photo

false

ajax Dimensions width false

If true, this setting forces ColorBox to display a link as a photo. Use this when automatic photo detection fails (such as using a url like 'photo.php' instead of 'photo.jpg') This property isn't actually used as ColorBox assumes all hrefs should be treated as either ajax or photos, unless one of the other content types were specified. Set a fixed total width. This includes borders and buttons. Example: "100%", "500px", or 500
Page 3 of 6

http://jacklmoore.com/colorbox/

ColorBox, A jQuery Lightbox

10/11/11 6:36 PM

height innerWidth innerHeight initialWidth initialHeight maxWidth maxHeight Slideshow slideshow slideshowSpeed slideshowAuto

false false false 300 100 false false

Set a fixed total height. This includes borders and buttons. Example: "100%", "500px", or 500 This is an alternative to 'width' used to set a fixed inner width. This excludes borders and buttons. Example: "50%", "500px", or 500 This is an alternative to 'height' used to set a fixed inner height. This excludes borders and buttons. Example: "50%", "500px", or 500 Set the initial width, prior to any content being loaded. Set the initial height, prior to any content being loaded. Set a maximum width for loaded content. Example: "100%", 500, "500px" Set a maximum height for loaded content. Example: "100%", 500, "500px"

false If true, adds an automatic slideshow to a content group / gallery. 2500 Sets the speed of the slideshow, in milliseconds. true If true, the slideshow will automatically start to play. "start slideshowStart Text for the slideshow start button. slideshow" "stop slideshowStop Text for the slideshow stop button slideshow" Positioning If true, ColorBox will be displayed in a fixed position within the visitor's fixed false viewport. This is unlike the default absolute positioning relative to the document. Accepts a pixel or percent value (50, "50px", "10%"). Controls ColorBox's top false vertical positioning instead of using the default position of being centered in the viewport. Accepts a pixel or percent value (50, "50px", "10%"). Controls ColorBox's bottom false vertical positioning instead of using the default position of being centered in the viewport. Accepts a pixel or percent value (50, "50px", "10%"). Controls ColorBox's left false horizontal positioning instead of using the default position of being centered in the viewport. Accepts a pixel or percent value (50, "50px", "10%"). Controls ColorBox's right false horizontal positioning instead of using the default position of being centered in the viewport. Callbacks onOpen false Callback that fires right before ColorBox begins to open. onLoad false Callback that fires right before attempting to load the target content. onComplete false Callback that fires right after loaded content is displayed. onCleanup false Callback that fires at the start of the close process. onClosed false Callback that fires once ColorBox is closed.

Public Methods
This method allows you to call ColorBox without having to assign it to an element.
http://jacklmoore.com/colorbox/ Page 4 of 6

ColorBox, A jQuery Lightbox

10/11/11 6:36 PM

$.colorbox()
$.colorbox({href:"login.php"});

$.colorbox.next() $.colorbox.prev() $.colorbox.close()

These methods moves to the next and previous items in a group and are the same as pressing the 'next' or 'previous' buttons. This method initiates the close sequence, which does not immediately complete. The lightbox will be completely closed only when the 'cbox_closed' event / onClosed callback is fired. This method is used to fetch the current HTML element that ColorBox is associated with. Returns a jQuery object containing the element.
var $element = $.colorbox.element();

$.colorbox.element()

This allows ColorBox to be resized based on it's own auto-calculations, or to a specific size. This must be called manually after ColorBox's content has loaded. $.colorbox.resize() The optional parameters object can accept 'width' or 'innerWidth' and 'height' or 'innerHeight'. Without specifying a width or height, ColorBox will attempt to recalculate the height of it's current content. This runs silently when the DOM is first loaded and is used to initialize the lightbox (adds necessary HTML to the DOM, preloads the interface graphics, $.colorbox.init() initializes variables, etc). If ColorBox were completely removed from the DOM, to load in a new stylesheet for example, this would be needed to re-initialize it. Removes all traces of ColorBox from the document. Not the same as $.colorbox.remove() $.colorbox.close(), which tucks colorbox away for future use.

Event Hooks
These event hooks fire at the same time as their corresponding callbacks (ie. cbox_complete & onComplete), but can be used to make a universal change to ColorBox, while callbacks are only applied to selected elements.
// Example of using an event listener and public method to build a primitive slideshow: $(document).bind('cbox_complete', function(){ setTimeout($.colorbox.next, 1500); });

triggers when ColorBox is first opened, but after a few key variable assignments take place. cbox_load triggers at the start of the phase where content type is determined and loaded. triggers when the transition has completed and the newly loaded content has been cbox_complete revealed. cbox_cleanup triggers as the close method begins. cbox_closed triggers as the close method ends. cbox_open About I'm a web developer, designer, author of ColorBox. I built this blog, so drop me an email if anything is
http://jacklmoore.com/colorbox/ Page 5 of 6

ColorBox, A jQuery Lightbox

10/11/11 6:36 PM

I'm a web developer, designer, author of ColorBox. I built this blog, so drop me an email if anything is broken or if you have suggestions. Thanks. RSS Follow me on Twitter Follow me on GitHub jQuery Plugins ColorBox jQuery lightbox. Need the FAQ? Autosize auto-sizing for textarea elements. Blend animated background effect. Monte small carousel animation. ClearType ClearType fix for IE7/IE8. Latest Posts Using Placeholder Attribute naturalWidth and naturalHeight in IE ColorBox with Flickr Feed ColorBox Beginner's Guide Threadless reprint of 'Tragedy Struck' Working with JavaScript click events JavaScript: working with URLs and GET Solving IE7 & IE8 PNG Opacity Problems Handling asynchronous JavaScript callbacks JavaScript: Slice, Substring, or Substr? Moving Beyond IE6 Tags ColorBox x2 CSS x1 Design x1 HTML5 x1 Internet Explorer x3 JavaScript x6 jQuery x5 [email protected]

http://jacklmoore.com/colorbox/

Page 6 of 6