Github

Colorbox FAQ

Additional Help

If your problem isn't covered in this FAQ, your best bet would be to post your question to Stack Overflow. Be sure to tag your question with colorbox and jQuery. Due to the volume of questions, I cannot offer individual support.

Beginner's Guide

If you are completely new to jQuery plugins, try reading the Colorbox beginner's guide

Common Problems

How To

Flash appears over Colorbox:

By default Flash will overlay any HTML content, including Colorbox. This can be prevented by setting the 'wmode' param and embed attributes to 'transparent'. See this post from Adobe Support for more information.

Colorbox is positioned incorrectly or behaving strangely:

This is often due to loading colorbox.css after jquery.colorbox.js or stems from a bad doctype. Both jQuery and colorbox.css need to be loaded prior to jquery.colorbox.js. Colorbox should be called or assigned to elements inside of jQuery's ready method, which should be declared after jquery.colorbox.js.

Colorbox requires a valid doctype and rendering in quirks mode is not supported. If you are not using the HTML5 doctype, make sure to include the full doctype declaration (with URI) to enable standards mode.

Unfortunately, this abbreviated doctype renders the document in quirks mode for Internet Explorer:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

The doctype with URI renders in standards mode for all browsers:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

For more information, see A List Apart's primer on doctypes and QuirksMode on quirks mode.

Colorbox is broken or looks incomplete while displaying documents:

Often this is due to not using an iframe when an iframe would be required. The default method, ajax, is only for elements that can exist within a <body> element.

If you are loading a complete HTML document with <html>, <head>, and <body> elements, then using an iframe is required. While nesting these elements may appear to display correctly in some browsers, it is still invalid HTML and should not be depended on. Remember to set the width and height values for Colorbox when using an iframe, it has no way of knowing the dimensions of elements that exist within the iframe.

Colorbox leverages jQuery's .load() method for handling ajax. If you are loading a document from the same domain as your current document, you can use a selector pull out just the portion of the document that is needed.

$('#example').colorbox({href:'document.html div#content'});

Colorbox only works the first time it is opened:

This is often due to loading a document with script elements with Colorbox's ajax mode instead of using an iframe. And iframe would prevent those scripts from interfering with the scripts in the host document. Often it's due to the parent document's version of jQuery being overwritten by the loaded in document's version of jQuery.

Trying to load an external page results in "Request unsuccessful"

This could be due to an invalid URL or trying to load ajax content from a different domain. Ajax will only work with documents that are on the same domain as your current document due to browser restrictions. Ajax has to be run from a server to function (e.g., ajax content is not going to work from your desktop unless you are running a web server such as Apache for local development).

JS Error: `$(selector).colorbox is not a function` or `$.colorbox is not a function`

Double check your script paths and look for accidentally including multiple versions of jQuery.

This most often happens when users load multiple versions of jQuery which overwrites the version that was extended with the Colorbox plugin. Check out source to see if a version of jQuery is being loaded after Colorbox has been loaded.

If your HTML document only contains one link to the jQuery library, the same error could also be caused by loading HTML snippets (through ajax) or HTML documents that load the jQuery library. If you are loading HTML snippets with ajax or through Colorbox, be sure that they do not contain a link to the jQuery library. HTML documents should be contained within iframes or opened with Colorbox's iframe property.

Closing Colorbox breaks accordians/tabs/animations

Try setting returnFocus to false. Colorbox returns focus to the element it was launched from upon closing. This is intended to provide better accessibility to users who use their keyboard to navigate through the document's links, but it can cause problems with some JS effects. The problem isn't Colorbox specific and can be reproduced without Colorbox by pressing the TAB key to cycle through the available links.

JavaScript/jQuery is not working inside of Colorbox.

This is often due to trying to access an element before it has been loaded into the document and can be resolved by moving the JavaScript into Colorbox's onComplete callback.

// Example the jQuery Forms plugin: http://jquery.malsup.com/form/
$('#login_window').colorbox({onComplete:function(){
    $('form#login').ajaxForm();
}});

Colorbox is sized too small the first time ajax/inline content is opened

This is likely due to IMG elements in the loaded markup having not fully finished downloading before Colorbox measures the content to determine the width and height it should use. The second time Colorbox is opened, the images have been cached and will take up the correct width and height within your document. This can easily be fixed by adding the width and height dimensions to the IMG element (a recommended practice), or by setting a style that specifies the width and height of the image in your CSS.

IE6/IE7 freezes with jQuery 1.6.0

jQuery 1.6.0 had a regressive bug that affects Colorbox. Either use jQuery 1.6.1 or higher.

Colorbox is not working with Microsoft SharePoint

The default master page used by SharePoint does not specify a doctype. Colorbox requires the browser render in strict mode, which is enabled by specifying a valid doctype at the very beginning of your HTML document. The master page will have to be edited so that it includes a doctype.

Also see the doctype entry in this FAQ

Inline forms not submitting / POSTing in ASP.NET

This happens because the entire form isn't being loaded into Colorbox, just the form fields. Since the form fields have been moved outside of their parent form element, the form is broken. The proper solution would be to include the parent form element together with the form field elements so that the form stays intact. However, this is impractical with ASP.NET forms as the entire content of the body element is wrapped with the form element. To work around this, move Colorbox's markup so that it and content displayed in it will reside within the form element. Example:

$(document).ready(function () {
    $("#colorbox, #cboxOverlay").appendTo('form:first');
    $("#link_to_form").colorbox({ width: "50%", inline: true, href: "#form_fields_container" });
});

You'll need to define a cookie that indicates that the user has already visited to site, then use that to determine whether or not to display Colorbox.

// Display a welcome message on first visit, and set a cookie that expires in 30 days:
if (document.cookie.indexOf('visited=true') === -1) {
    var expires = new Date();
    expires.setDate(expires.getDate()+30);
    document.cookie = "visited=true; expires="+expires.toUTCString();
    $.colorbox({html:"Welcome!"});
}

Pass Colorbox parameters based on a URL

With a little JavaScript, you can parse the parameters from your URL's querystring and pass them to Colorbox.

// example url: http://example.com/gallery.html?open=true&amp;height=500
function getParameters(){
    var
    settingsObject = {},
    hash,
    hashes =  location.search.substring(1).split(/&amp;/),
    i;

    for (i = 0; i &lt; hashes.length; i++) {
        hash = hashes[i].split('=');
        settingsObject[hash[0]] = hash[1];
    }
    return settingsObject;
}
$('a.example').colorbox($.extend({width:'100%', height:'100%', speed:0}, getParameters()));

Here we selected some elements in our document, assigned colorbox to them, then used jQuery's $.extend() method to combine our querystring parameters with the initial settings we set for our elements. This is just an example however, and you probably should not let visitors control all of Colorbox's parameters (through modifying the querystring).

Prevent Colorbox from closing / Change the behavior of $.colorbox.close

Colorbox's close method can be cached and redefined as to control what happens when Colorbox is closed. This affects controls that are bind to it (such as the escKey, overlayClose, and the close button) and calling the close method directly. For example, let's open Colorbox to display a form element and redefine the close method to warn the visitor that they will discard their input if they try to close Colorbox before they submit their data.

var originalClose = $.colorbox.close;
$.colorbox.close = function(){
    var response;
    if($('#cboxLoadedContent').find('form').length > 0){
        response = confirm('Do you want to close this window?');
        if(!response){
            return; // Do nothing.
        }
    }
    originalClose();
};
$('a#example').colorbox();

Disable grouping by rel attribute

Set Colorbox's rel property to 'nofollow'.

$('a[rel="examples"]').colorbox({rel:'nofollow'});

Control Colorbox from within an iframe

An iframed document's window object will have a parent property that is used to get the parent's window object. The parent window's scripts (jQuery/Colorbox) can be accessed through that parent property:

<!-- calling colorbox's close method from within an iframe: -->
<a href='#' onclick='parent.$.colorbox.close(); return false;'>close this iframe</a>

<!-- open colorbox in the parent of an iframed document -->
<a onclick='parent.$.colorbox({href:"login.php"}); return false;'>open in parent window</a>

Create a separate link for opening a gallery

Lets say you've assigned Colorbox to a set of links in your document, but you also want to have an "Open Gallery" link that opens the first item in your set. When "Open Gallery" is clicked, you want to prevent the default action, then trigger a click event on that first set item.

var $gallery = $("a[rel=gallery]").colorbox();
$("a#openGallery").click(function(e){
    e.preventDefault();
    $gallery.eq(0).click();
});

Track Colorbox usage with Google Analytics

This can be done by calling the tracker and passing it the URL you want to log once Colorbox has displayed the content. Either use Colorbox's 'onComplete' callback or bind to the 'cbox_complete' event. The tracking method depends on whether you are using Google's traditional tracker or the newer asynchronous tracker. Examples:

// async tracker
$(document).bind("cbox_complete", function(){
    var href = $.colorbox.element().attr("href");
    if (href) {
        _gaq.push(["_trackPageview", href]);
    }
});

// traditional tracker
$(document).bind("cbox_complete", function(){
    var href = $.colorbox.element().attr("href");
    if (href) {
        pageTracker._trackPageview(href);
    }
});

Change Colorbox's default settings

The default settings can be changed by accessing the settings object and assigning it new values. The new values must be set before Colorbox is assigned to any elements in your markup, otherwise they will not be applied.

// change defaults individually:
$.colorbox.settings.opacity = 0.5;
$.colorbox.settings.speed = 0;
$.colorbox.settings.close = 'Exit';

// or use jQuery's $.extend() to change many defaults at once:
$.extend($.colorbox.settings, {opacity:0.5, speed:0, close:'Exit'});

Colorbox can be passed a function to be evaluated in place of a static value for any of it's properties. Through that any sort of string formatting or markup building can be done and displayed as the title:

$('a.gallery').colorbox({title:function () {
    return "To view full size, " + "click here!".link(this.href);
}});

Hey,

Follow me on Twitter and Github, that's where I'm most active these days. I welcome email (), but I'm afraid I no longer have time to answer personal requests for help regarding my plugins or posts. Thanks!