jQuery Waiting - spinners and progress bars

Get Started

Highly Recommended

Subscribe to my newsletter and follow me @practicalweb.

It is important to let your users know what they're doing, waiting! For the developer they need support in every browser, easy customization, and efficiency. Even though all this is possible with fancy CSS transformation, many browsers won't support it (IE < 10). jQuery Waiting uses standard, widely accepted css to style your waiting spinner, and a little jQuery to make it function. Best of all it works with Zepto too!

Donation

Car BounceTry my new app to keep you informed of your car's financing status and value.

Has Waiting been helpful to you?

Download

Version

Version 0.3

Last updated on 06/25/2013

jQuery Waiting is currently available for use in all personal or commercial projects under both MIT and GPL licenses. This means that you can choose the license that best suits your project, and use it accordingly.

Examples

Basic Initialization

Create a waiting animation, '#waiting1' is a simple empty div:

/* CSS:
.waiting{ padding: 0; display: inline-block; }
.waiting-element{ margin: 0 2px 2px 0; background-color: #ccc; 
	width: 10px; height: 20px; display: inline-block;}
.waiting-play-0{ margin-bottom: 0; background-color: #999; }
.waiting-play-1{ margin-bottom: 1px; background-color: #aaa; }
.waiting-play-2{ margin-bottom: 2px; background-color: #bbb; }
*/

$('#waiting1').waiting({ 
	elements: 10, 
	auto: true 
});

Styling

Here we specify only three elements and change the class to match our css:

/* CSS: Notice 'waiting-blocks' className matches waiting option
.waiting-blocks{ padding: 0; display: inline-block; }
.waiting-blocks-element{ background-color: #caddfb; border: solid 1px #c9ccdb;
	margin: 0 2px 0 0; width: 10px; height: 10px; display: inline-block; 
	-moz-border-radius: 4px; -webkit-border-radius: 4px; border-radius: 4px;}
.waiting-blocks-play-0{ background-color: #b0c5ee; }
.waiting-blocks-play-1{ background-color: #caddfb; }
*/

$('#waiting2').waiting({ 
	className: 'waiting-blocks', 
	elements: 3, 
	speed: 300, 
	auto: true 
});

Non-Fluid

Create a spinner that is not fluid, meaning once the lead play frame reaches the end it starts over, it does not fluidly wrap around:

/* CSS:
.waiting-nonfluid{ padding: 0; display: inline-block; }
.waiting-nonfluid-element{ margin: 0 2px 0 0; background-color: #ccc; 
	width: 10px; height: 20px; display: inline-block;}
.waiting-nonfluid-play-0,
.waiting-nonfluid-play-1,
.waiting-nonfluid-play-2,
.waiting-nonfluid-play-3,
.waiting-nonfluid-play-4,
.waiting-nonfluid-play-5{ background-color: #999; }
*/

$('#waiting3').waiting({ 
	className: 'waiting-nonfluid',
	elements: 5, 
	fluid: false,
	auto: true 
});

Circles

By using the radius option you can create a circle:

/* CSS: notice position: relative, width, and height are set for circles
.waiting-circles{ padding: 0; display: inline-block; 
	position: relative; width: 60px; height: 60px;}
.waiting-circles-element{ margin: 0 2px 0 0; background-color: #e4e4e4; 
	border: solid 1px #f4f4f4;
	width: 10px; height: 10px; display: inline-block; 
	-moz-border-radius: 4px; -webkit-border-radius: 4px; border-radius: 4px;}
.waiting-circles-play-0{ background-color: #9EC45F; }
.waiting-circles-play-1{ background-color: #aEd46F; }
.waiting-circles-play-2{ background-color: #bEe47F; }
*/

$('#waiting4').waiting({ 
	className: 'waiting-circles', 
	elements: 8, 
	radius: 20, 
	auto: true 
});

Using Methods and Events

Use some methods to start, stop, disable:

Play | Pause | Enable | Disable | Option
var $el = $('#waiting5');
$el.waiting({ elements: 10 });

// clicking the links to play/pause/enable/disable
$('#waiting5_play').click(function(e){
	$el.waiting('play');
	return false;
});
$('#waiting5_pause').click(function(e){
	$el.waiting('pause');
	return false;
});
$('#waiting5_enable').click(function(e){
	$el.waiting('enable');
	return false;
});
$('#waiting5_disable').click(function(e){
	$el.waiting('disable');
	return false;
});
$('#waiting5_option').click(function(e){
	if($el.waiting('option','className') == 'waiting')
		$el.waiting('option',{ className: 'waiting-blocks', elements: 5 });		
	else $el.waiting('option',{ className: 'waiting', elements: 10 });
	return false;
});

// open your console to watch these events
$el.bind('waiting:play waiting:pause waiting:enable waiting:disable', function(e){
	if(window.console)
		console.log(e.type);
});

Progress bar

Use the percent option and events to create an interactive progress bar.

25% | 50% | 75% | 100%
var $el = $('#waiting6');
$el.waiting({ 
	className: 'waiting-blocks',
	elements: 10, 
	auto: true 
});

// clicking the links to 25, 50, 75, 100%
$('#waiting6_25').click(function(e){
	e.preventDefault();
	$el.waiting('option',{ percent: 25 });	
});
$('#waiting6_50').click(function(e){
	e.preventDefault();
	$el.waiting('option',{ percent: 50 });	
});
$('#waiting6_75').click(function(e){
	e.preventDefault();
	$el.waiting('option',{ percent: 75 });	
});
$('#waiting6_100').click(function(e){
	e.preventDefault();
	$el.waiting('option',{ percent: 100 });	
});

The Options

// string - which tag type to use
tag: 'div',

// string - class name to use
className: 'waiting',

// integer - number of items to create
elements: '5',

// hash - hash of css properties for the parent element
// stylesheets are suggested but this is useful for size adjustments
css: {},

// hash - hash of css properties for each child element
// stylesheets are suggested but this is useful for size adjustments
elementsCss: {},

// integer - radius specifies to position in a circle
// defaults to false, indicating no circular position
radius: false,

// boolean - allows scene to roll over before completing
fluid: true,

// integer - speed to animate
speed: 100,

// the limit to allow, integer 0-100 for percent
percent: 100,

// boolean - whether to auto play
auto: false

The Methods

// Initialize a waiting instance
$el.waiting({});

// Enable a waiting, only begins playing if auto: true
$el.waiting('enable');

// Play the animation
$el.waiting('play');

// Pause the animation, leaves all animations styles in place
$el.waiting('pause');

// Disable a waiting, removes all animation styles
$el.waiting('disable');

// Destroy a waiting
$el.waiting('destroy');

// Get or set an option. When value is provided a Set takes place
// If only the key is provided the value will be retrieved
$el.waiting('option', key, value);

// if an object is passed each setting will be applied
$el.waiting('option', { speed: 500 });

// set global defaults
$.waiting.setDefaults({ auto: true });

The Events

// when the control is enabled/created
$el.bind('enable.waiting', function(e){});

// when the control starts playing
$el.bind('play.waiting', function(e){});

// when the control is paused
$el.bind('pause.waiting', function(e){});

// when the control is disabled
$el.bind('disable.waiting', function(e){});

// when the control is destroyed
$el.bind('destroy.waiting', function(e){});