jQuery LoadingOverlay

Quick Demo

Features

• Shows a loading overlay on the whole page or over single DOM elements
• Tracks a “counter” (or a queue) to allow multiple calls on single target
• Can auto resize according to its container (very useful if used over a DOM element being filled meanwhile)
• Completely configurable
• No external CSS, small footprint

Methods

There are three different methods, one to attach a Loading Overlay to the body and thus covering the whole page, another to attach it to a single DOM element or a set of DOM elements and the last one to set the default parameters.

$.LoadingOverlay(action [,options])

Shows the Loading Overlay with a fixed position, covering the whole page. Optionally pass some options to it.
This method doesn’t return anything.

$(selector).LoadingOverlay(action [,options])

Attach the Loading Overlay to a single DOM element or a set of DOM elements. Optionally pass some options to it.
This method return a jQuery object or a set of jQuery objects (depending on the selector used) and is chainable.

$.LoadingOverlaySetup(options)

Set default options for all future calls to $.LoadingOverlay and $(selector).LoadingOverlay.

Actions

The $.LoadingOverlay and $(selector).LoadingOverlay methods have two variants, corresponding to two actions:

$[(selector)].LoadingOverlay(“show” [,options])

Show a Loading Overlay, or increase the counter if it’s already shown. Optionally you can pass a set of options, but note that they only take effect if the Loading Overlay is not shown yet on the element.

$[(selector)].LoadingOverlay(“hide” [,force])

Hide the Loading Overlay or decrease the counter if it’s more than 1. You can optionally pass a boolean parameter force to hide the Loading Overlay even if the counter hasn’t reached 0.

Options and defaults values

color           : "rgba(255, 255, 255, 0.8)",  // String
image           : "loading.gif",               // String
maxSize         : "100px",                     // Integer/String
minSize         : "20px",                      // Integer/String
resizeInterval  : 0,                           // Integer
size            : "50%"                        // Integer/String

color

CSS background-color property. Use rgba to set the opacity.

image

URL of the image to show. Use an empty string "" or false to show no image.

maxSize

Maximun size of image in pixels. Set it to 0 or false for no limit.

minSize

Minimun size of image in pixels. Set it to 0 or false for no limit.

resizeInterval

Specifies an interval in milliseconds to resize the Loading Overlay accoring to its container.
Use this when the DOM element is supposed to change size while the Loading Overlay is shown.
Use 0 or false to disable this feature.

size

Size of image in percentage. Use 0 or false to disable image resizing.

Examples

Example 1 - Whole page Overlay

// Show full page Loading Overlay
$.LoadingOverlay("show");

// Hide it after 3 seconds
setTimeout(function(){
    $.LoadingOverlay("hide");
}, 3000);

Example 2 - Single element Overlay

// Let's call it 2 times just for fun...
$("#element").LoadingOverlay("show");
$("#element").LoadingOverlay("show");

// Here we might call the "hide" action 2 times, or simply set the "force" parameter to true:
$("#element").LoadingOverlay("hide", true);

Example 3 - Single element Overlay with auto resize

Place a test div in your html page like that:

<div id="element" style="width:50px; height:50px; background:red; border:2px solid black;"></div>

And try the auto resize feature:

$("#element").LoadingOverlay("show", {
    resizeInterval : 20
});

setInterval(function(){
    if ($("#element").width() < 500) $("#element").height("+=5").width("+=10");
}, 300);

Example 4 - Use the counter feature to hide the Loading Overlay only when all Ajax calls are completed

$(document).ajaxStart(function(){
    $.LoadingOverlay("show");
});
$(document).ajaxStop(function(){
    $.LoadingOverlay("hide");
});
// Now try to make a few Ajax calls, a Loading Overlay will be shown until the last call is completed!

Example 5 - Set Defaults

$.LoadingOverlaySetup({
     color           : "rgba(0, 0, 0, 0.4)",
     image           : "img/custom_loading.gif",
     maxSize         : "80px",
     minSize         : "20px",
     resizeInterval  : 0,
     size            : "50%"
});

Comments and Ideas

Want to leave a comment or give me an idea? Email me or visit this Post.