Usage
ColorBox accepts settings from an object of key/value pairs, andcan be assigned to any HTML element.
// Format:$(selector).colorbox({key:value, key:value, key:value});
// 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 | Default | Description |
---|---|---|
transition | "elastic" | The transition type. Can be set to "elastic", "fade", or"none". |
speed | 350 | Sets the speed of the fade and elastic transitions, inmilliseconds. |
href | false | This can be used as an alternative anchor URL or to associate a URLfor non-anchor elements such as images or form buttons.$("h1").colorbox({href:"welcome.html"}); |
title | false | This can be used as an anchor title alternative for ColorBox. |
rel | false | This can be used as an anchor rel alternative for ColorBox. Thisallows the user to group any combination of elements together for agallery, or to override an existing rel so elements are not groupedtogether.$("a.gallery").colorbox({rel:"group1"});Note: The value can also be set to 'nofollow' to disablegrouping. |
scalePhotos | true | If true, and if maxWidth, maxHeight, innerWidth, innerHeight,width, or height have been defined, ColorBox will scale photos tofit within the those values. |
scrolling | true | If false, ColorBox will hide scrollbars for overflowing content.This could be used on conjunction with the resize method (seebelow) for a smoother transition if you are appending content to analready open instance of ColorBox. |
opacity | 0.85 | The overlay opacity level. Range: 0 to 1. |
open | false | If true, ColorBox will immediately open. |
returnFocus | true | If true, focus will be returned when ColorBox exits to the elementit was launched from. |
fastIframe | true | If false, the loading graphic removal and onComplete event will bedelayed until iframe's content has completely loaded. |
preloading | true | Allows for preloading of 'Next' and 'Previous' content in a group,after the current content has finished loading. Set to false todisable. |
overlayClose | true | If false, disables closing ColorBox by clicking on the backgroundoverlay. |
escKey | true | If false, will disable closing colorbox on 'esc' key press. |
arrowKey | true | If false, will disable the left and right arrow keys fromnavigating between the items in a group. |
loop | true | If false, will disable the ability to loop back to the beginning ofthe group when on the last element. |
current | "image {current} of {total}" | Text or HTML for the group counter while viewing a group. {current}and {total} are detected and replaced with actual numbers whileColorBox runs. |
previous | "previous" | Text or HTML for the previous button while viewing a group. |
next | "next" | Text or HTML for the next button while viewing a group. |
close | "close" | Text or HTML for the close button. The 'esc' key will also closeColorBox. |
data | false | For submitting GET or POST values through an ajax request. The dataproperty will act exactly like jQuery's.load()dataargument, as ColorBox uses .load() for ajax handling. |
Content Type | ||
iframe | false | If true, specifies that content should be displayed in aniFrame. |
inline | false | If true, content from the current document can be displayed bypassing the href property a jQuery selector, or jQuery object. // Using a selector:$("#inline").colorbox({inline:true, href:"#myForm"});// Using a jQuery object:var $form = $("#myForm");$("#inline").colorbox({inline:true, href:$form}); |
html | false | For displaying a string of HTML or text. $.colorbox({html:"<p>Hello</p>"}); |
photo | 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 urllike 'photo.php' instead of 'photo.jpg') |
ajax | This property isn't actually used as ColorBox assumes all hrefsshould be treated as either ajax or photos, unless one of the othercontent types were specified. | |
Dimensions | ||
width | false | Set a fixed total width. This includes borders and buttons.Example: "100%", "500px", or 500 |
height | false | Set a fixed total height. This includes borders and buttons.Example: "100%", "500px", or 500 |
innerWidth | false | This is an alternative to 'width' used to set a fixed inner width.This excludes borders and buttons. Example: "50%", "500px", or500 |
innerHeight | false | This is an alternative to 'height' used to set a fixed innerheight. This excludes borders and buttons. Example: "50%", "500px",or 500 |
initialWidth | 300 | Set the initial width, prior to any content being loaded. |
initialHeight | 100 | Set the initial height, prior to any content being loaded. |
maxWidth | false | Set a maximum width for loaded content. Example: "100%", 500,"500px" |
maxHeight | false | Set a maximum height for loaded content. Example: "100%", 500,"500px" |
Slideshow | ||
slideshow | false | If true, adds an automatic slideshow to a content group /gallery. |
slideshowSpeed | 2500 | Sets the speed of the slideshow, in milliseconds. |
slideshowAuto | true | If true, the slideshow will automatically start to play. |
slideshowStart | "start slideshow" | Text for the slideshow start button. |
slideshowStop | "stop slideshow" | Text for the slideshow stop button |
Positioning | ||
fixed | false | If true, ColorBox will be displayed in a fixed position within thevisitor's viewport. This is unlike the default absolute positioningrelative to the document. |
top | false | Accepts a pixel or percent value (50, "50px", "10%"). ControlsColorBox's vertical positioning instead of using the defaultposition of being centered in the viewport. |
bottom | false | Accepts a pixel or percent value (50, "50px", "10%"). ControlsColorBox's vertical positioning instead of using the defaultposition of being centered in the viewport. |
left | false | Accepts a pixel or percent value (50, "50px", "10%"). ControlsColorBox's horizontal positioning instead of using the defaultposition of being centered in the viewport. |
right | false | Accepts a pixel or percent value (50, "50px", "10%"). ControlsColorBox's horizontal positioning instead of using the defaultposition 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 targetcontent. |
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
$.colorbox() | This method allows you to call ColorBox without having to assign itto an element.$.colorbox({href:"login.php"}); |
$.colorbox.next() $.colorbox.prev() | These methods moves to the next and previous items in a group andare the same as pressing the 'next' or 'previous' buttons. |
$.colorbox.close() | This method initiates the close sequence, which does notimmediately complete. The lightbox will be completely closed onlywhen the 'cbox_closed' event / onClosed callback is fired. |
$.colorbox.element() | This method is used to fetch the current HTML element that ColorBoxis associated with. Returns a jQuery object containing the element.var $element = $.colorbox.element(); |
$.colorbox.resize() | This allows ColorBox to be resized based on it's ownauto-calculations, or to a specific size. This must be calledmanually after ColorBox's content has loaded. The optionalparameters object can accept 'width' or 'innerWidth' and 'height'or 'innerHeight'. Without specifying a width or height, ColorBoxwill attempt to recalculate the height of it's currentcontent. |
$.colorbox.remove() | Removes all traces of ColorBox from the document. Not the same as$.colorbox.close(), which tucks colorbox away for future use. |
Event Hooks
These event hooks fire at the same time as their correspondingcallbacks (ie. cbox_complete & onComplete), but canbe used to make a universal change to ColorBox, while callbacks areonly 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);});
cbox_open | triggers when ColorBox is first opened, but after a few keyvariable assignments take place. |
cbox_load | triggers at the start of the phase where content type is determinedand loaded. |
cbox_complete | triggers when the transition has completed and the newly loadedcontent has been revealed. |
cbox_cleanup | triggers as the close method begins. |
cbox_closed | triggers as the close method ends. |