Example of usage

Year Numbers Status Another
2013 23,789.23 Finished Good
2014 19,990.11 Open Bad
2015 8,123.42 Open Ugly
setInterval(function() {
  $('#example-table').loading('toggle');
}, 2000);

See more examples

Getting started

  1. Install from bower:

    $ bower install jquery-loading

    Or download the source code on github.

  2. Include jquery and jquery-loading in your page:

    <script src="http://code.jquery.com/jquery-1.11.0.min.js"></script>
    <script src="jquery.loading.js"></script>
  3. Call the plugin in the element you want to add the loading state:

    $("#some-element").loading();
  4. (optional) If you want to use some default themes and styles (like the ones used on this page), include the CSS file:

    <link href="jquery.loading.css" rel="stylesheet">

    You don't need to include it if you are using a custom overlay element.

Motivation

The idea is to lock elements that are loading or working (in decorrence of an Ajax request, for example) while keeping the rest of the page available to the user.

Jquery-loading does that by adding an overlay on top of the loading element.

You can customize this overlay however you want or use our default themes. It's your call.


Basic usage

Starting

This div is always loading

Stopping

This div will stop loading if you click it

Toggling

This div is toggling the loading state

Full page loader

$('body').loading({
  stoppable: true
});

States and events

loading.start

Triggered when the loading state is started. Receives the loading object as parameter. Example:

$('#my-element').on('loading.start', function(event, loadingObj) {
  // do something whenever the loading state of #my-element is turned on
});

loading.stop

Triggered when the loading state is stopped. Receives the loading object as parameter. Example:

$('#my-element').on('loading.stop', function(event, loadingObj) {
  // do something whenever the loading state of #my-element is turned off
});

loading.click

Triggered when the overlay element is clicked. Receives the loading object as parameter. Example:

$('#my-element').on('loading.click', function(event, loadingObj) {
  // do something whenever the loading overlay of #my-element is clicked
});

Initializing

There is a shortcut to provide event handlers at initilization:

$('#my-element').loading({
  onStart: function(loadingObj) { ... },
  onStop: function(loadingObj) { ... },
  onClick: function(loadingObj) { ... }
});

The :loading selector

Use it to get elements with the loading state currently on.

$(':loading') // Get all the elements with the loading state on
$('#element').is(':loading') // Check if the '#element' is loading
Custom loading...

Customization

Custom overlay

This div has a custom overlay element

Custom animation

This div has a custom start / stop animation

Themes and default styles

You must include the dist/jquery.loading.css file in your page if you want to use the default themes. If you're working with a custom overlay element, the following options have no effect.

Light theme

This div has the light theme

Dark theme

This div has the dark theme

Custom message

This div has a custom loading message

Full list of options

Option Default value Comments
overlay - jQuery element to be used as overlay. If not informed, the plugin will create a default one
message Loading... Message to be rendered on the overlay content. Has no effect if a custom ovelay was informed
theme light Theme to be used for the overlay element. Some default themes are defined on the jquery.loading.css file (include it if you want to use the default themes). Has no effect if a custom ovelay was informed
shownClass loading-shown Class(es) to be applied to the overlay element when the loading state is started
hiddenClass loading-hidden Class(es) to be applied to the overlay element when the loading state is stopped
stoppable false Setting this option to true will make the loading state be stopped if the overlay element is clicked by the user. This option does not override the onClick option
start true Define whether to start or not the loading state when the plugin is initialized
onStart loading.overlay.fadeIn(150) Function to be executed when the loading state is started. Receives the loading object as parameter
onStop loading.overlay.fadeOut(150) Function to be executed when the loading state is stopped. Receives the loading object as parameter
onClick - Function to be executed when the overlay is clicked. Receives the loading object as parameter

Methods of Interest

Method Return type Description Example
jQuery.fn.loading jQuery Initializes the plugin. $('#my-loading-element').loading({ ... })
jQuery.fn.Loading Loading Return the internal plugin object associated to the jQuery element. Also initialize the plugin if this the first call using this target. Note that this function is different from the common $.fn.loading wich start the plugin and return a chainable jQuery object. $('#my-loading-element').Loading()
resize jQuery Recalculate and apply new dimensions and position to the overlay, based on the state of the target element. Call this method if the the overlay is not being shown on the right position and/or dimensions. $(...).loading('resize')
start jQuery Turn on the loading state of some element and trigger the loading.start event. $(...).loading('start')
stop jQuery Turn off the loading state of some element and trigger the loading.stop event. $(...).loading('stop')
destroy jQuery Remove from DOM the overlay element. $(...).loading('destroy')
toggle jQuery Turn on or off the loading state of some element, depending of the current state, and trigger the respective event. $(...).loading('toggle')
$.Loading.setDefaults - Extend the Loading plugin default options $.Loading.setDefaults({ theme: 'blurred', ... })