Gaspare Sganga

IT Manager, GIS Analyst & Lead Developer @setin.

Freelance Developer & Consultant.

Buy me a coffee?
10 February 2018 : Version 1.6.0 released. See release notes.
Do you like this plugin? Great! Then why don't you try my other jQuery plugins?


Quick Demo

Get it


View project on GitHub or download the latest release.


npm install gasparesganga-jquery-loading-overlay


bower install gasparesganga-jquery-loading-overlay


CDN hosting of this library is possible thanks to jsDelivr. For more details about URL structure please refer to the official documentation.
On the CDN configuration page you can find all the available files and versions of this library, select a specific version, use range or latest version aliasing, join more files in a single request and enable subresource integrity (SRI).


  • Shows a loading overlay on the whole page or over single DOM elements
  • Tracks a counter 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)
  • Compatible with Font Awesome
  • Can show a custom element to provide feedback to the user
  • Completely configurable
  • No external CSS, small footprint


There are three different methods, one to attach a LoadingOverlay 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 LoadingOverlay 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 LoadingOverlay to a single DOM element or a set of DOM elements. Optionally pass some options to it.
This method returns a jQuery object or a set of jQuery objects (depending on the selector used) and is chainable.


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


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


$[(selector)].LoadingOverlay("show" [,options])
Shows a LoadingOverlay, or increases the counter if it’s already shown. Optionally you can pass a set of options, but note that they only take effect if the LoadingOverlay is not shown yet on the element.


$[(selector)].LoadingOverlay("hide" [,force])
Hides the LoadingOverlay or decreases the counter if it’s more than 1. You can optionally pass a boolean parameter force to hide the LoadingOverlay even if the counter hasn’t reached 0.

Options and defaults values

color           : "rgba(255, 255, 255, 0.8)"    // String
custom          : ""                            // String/DOM Element/jQuery Object
fade            : true                          // Boolean/Integer/String/Array
fontawesome     : ""                            // String
image           : "data:image/gif;base64,..."   // String
imagePosition   : "center center"               // String
maxSize         : "100px"                       // Integer/String
minSize         : "20px"                        // Integer/String
resizeInterval  : 50                            // Integer
size            : "50%"                         // Integer/String
zIndex          : 9999                          // Integer

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


A DOM element, jQuery object or plain HTML to append to the LoadingOverlay. You can use this feature to display some feedback for your user (see example 4 ).
Use an empty string "" or false to disable the feature.


Controls the fade in and fade out durations. It can be either 0 or false to disable it (meaning a zero duration), an integer or string to set equal fade in and fade out durations (ie. 400 or "fast" or "slow") or a two-elements array to set specific fade in and fade out durations (ie. [600, 300]). You can also pass the boolean value true, which is treated like [400, 200].


Class(es) of the Font Awesome icon to use. Note that you must include the Font Awesome stylesheet in your project if you wish to use this feature. Use an empty string "" or false to disable the feature.


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


This option is mapped directly to CSS background-position property to customize the position of the image.


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


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


Specifies an interval in milliseconds to resize and reposition the LoadingOverlay according to its container. This is useful when the container element changes size and/or position while the LoadingOverlay is being shown.
Set it to 0 or false to disable this feature.


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


Use this to explicitly set a z-index for the overlay. This is useful when LoadingOverlay is used with other z-index intensive libraries like Bootstrap.


Example 1 - Whole page Overlay

// Show full page LoadingOverlay

// Hide it after 3 seconds
}, 3000);

Example 2 - Single element Overlay

// Let's call it 2 times just for fun...

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

Example 3 - Use Font Awesome spinner instead of gif image

$.LoadingOverlay("show", {
    image       : "",
    fontawesome : "fa fa-spinner fa-spin"

Example 4 - Show a countdown in a custom element

var count           = 5;
var customElement   = $("<div>", {
    id      : "countdown",
    css     : {
        "font-size" : "50px"
    text    : count

$.LoadingOverlay("show", {
    image   : "",
    custom  : customElement

var interval = setInterval(function(){
    if (count <= 0) {
}, 1000);

Example 5 - Display a LoadingOverlay during each Ajax request

You can rely on .ajaxStart() and .ajaxStop() to show and hide the LoadingOverlay during every Ajax request:

// Now try to make a few Ajax calls, a LoadingOverlay will be shown until the last call is completed!

Or, in case you need some more sophisticated control/filter, you can use .ajaxSend() and .ajaxComplete() in the same way. LoadingOverlay will take care of multiple calls thanks to its internal counter feature.

$(document).ajaxSend(function(event, jqxhr, settings){
$(document).ajaxComplete(function(event, jqxhr, settings){
// Now try to make a few Ajax calls, a LoadingOverlay will be shown until the last call is completed!

Example 6 - Play with extreme fade durations

$.LoadingOverlay("show", {
    fade  : [2000, 1000]

Example 7 - Set Defaults

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


With release 1.2 I have started to include some extras to accomodate feedback and requests by the users, yet avoiding to bloat the plugin with non-essential functionalities that are really case-specific. They can be thought as plugin modules of LoadingOverlay that provide additional features.


This extra provides basic progress bar loader functionality.
The idea is very similar to the one that led to the custom option: providing some feedback to the user while the LoadingOverlay is being shown.
In some cases, a kind of progress bar could fit this need very well. So instead of creating your own progress bar, you can use an instance of LoadingOverlayProgress.
The code is easily customizable for your specific taste, but you can use it right out-of-the-box since some customization options are available and should be enough for most cases:

// Initialize Progress and show LoadingOverlay
var progress = new LoadingOverlayProgress();
$.LoadingOverlay("show", {
    custom  : progress.Init()

// Simulate some action:
var count     = 0;
var interval  = setInterval(function(){
    if (count >= 100) {
        delete progress;
}, 100)


You can customize the look of the progress bar and text passing and object with bar and text properties to the new instance. Any CSS property is accepted.
You can pass a boolean value false to the text property to disable it.

var progressCustom = new LoadingOverlayProgress({
    bar     : {
        "background"    : red,
        "top"           : "50px",
        "height"        : "30px",
        "border-radius" : "15px"
    text    : {
        "color"         : red,
        "font-family"   : "monospace",
        "top"           : "25px"


10 February 2018 - Version 1.6.0
29 September 2017 - Version 1.5.4
27 January 2017 - Version 1.5.3
9 December 2016 - Version 1.5.2
11 November 2016 - Version 1.5.1
11 November 2016 - Version 1.5.0
5 August 2016 - Version 1.4.1
29 June 2016 - Version 1.4.0
25 May 2016 - Version 1.3
22 April 2016 - Version 1.2
31 December 2015 - Version 1.1
15 February 2015 - Version 1.0

Comments and Ideas

Want to leave a comment or give me an idea? Send me an or use the comments section below.