Spinner – A jQuery Preloader Plugin
About
Spinner provides a simple approach for adding and removing a preloader for your web applications. Usage is as simple as calling $(‘elem’).spinner() and subsequently $(‘elem’).spinner(‘remove’). You may create your own custom preloaders at http://www.ajaxload.info. Please note that if you use a custom preloader, you must pass in the new height and width as options.
Configuration Options
Spinner has a short list of customizable options to give you the flexibility you need. Please visit the usage page for examples of how to use these options properly.
| Option | Description | Default Value |
|---|---|---|
| img | The relative path to the preloader image to be used. You may create a custom preloader image at ajaxload.info. If you use a custom preloader, you must update the height and width options to match the new image size. | spinner.gif |
| position | The position to display the spinner relative to the parent element. Options are left, center, and right. | right |
| height | The height of the preloader image. Used in calculating the vertical positioning. Must be an integer. | 16 |
| width | The width of the preloader image. Used in calculating the horizontal positioning. Must be an integer. | 16 |
| zIndex | The z-index of the preloader image. Useful when you have other absolutely positioned elements on the page with varying z-index values. Must be an integer. | 1001 |
| hide | Determines whether the element that triggered the preloaded image should be hidden or not. If true, the element is hidden using CSS visibility as to preserve your current site layout. The element is displayed again upon closing the spinner with $(‘yourElem’).spinner(‘remove’);. Must be a boolean value (true/false). | false |
| onStart | A user defined custom callback function that is triggered before displaying the preloader. | function() { } |
| onFinish | A user defined custom callback function that is triggered when a user removes a spinner using$(‘yourElem’).spinner(‘remove’);. Occurs after the spinner has been removed. | function() { } |
Example Usage
The following 4 examples demonstrate Spinner usage in a nutshell.
Click here to view the examples in action.
Example 1
The spinner is displayed to the right of the clicked element for 5 seconds.
$('#example1').click(function() {
var $this = $(this);
$this.spinner();
setTimeout(function() {
$this.spinner('remove');
}, 5000);
return false;
});
Example 2
The spinner is displayed centered over the clicked element for 5 seconds and the element is hidden using visibility to maintain layout positioning.
$('#example2').click(function() {
var $this = $(this);
var opts = { position: 'center', hide: true };
$this.spinner(opts);
setTimeout(function() {
$this.spinner('remove');
}, 5000);
return false;
});
Example 3
The spinner is displayed to the left of multiple items that have a matching class for 2 seconds.
$('#example3').click(function() {
var $this = $('.example3');
var opts = { position: 'left' };
$this.spinner(opts);
setTimeout(function() {
$this.spinner('remove');
}, 2000);
return false;
});
Example 4
A large, non-default preloader is used which means we need to override the options for img, height, and width. The spinner is displayed to the right of the url and both onStart and onFinish callback options are used. The callbacks simply alert you in this case as an example.
$('#example4').click(function() {
var $this = $(this);
var opts = {
img: 'spinner-large.gif',
height: 48,
width: 48,
onStart: function() { alert('onStart callback alert'); },
onFinish: function() { alert('onFinish callback alert, 2 seconds are up.'); }
};
$this.spinner(opts);
setTimeout(function() {
$this.spinner('remove');
}, 2000);
return false;
});
Downloads
Downloads are currently available from the following sources:
Support
If you are having issues with Spinner you may post a comment below or submit a bug report on the official jQuery plugin homepage.
Suggestions and feature requests are also welcome.
Change Log
Spinner 1.0.0
- Initial release on 05/14/10
Hey, you can check out a great jQuery Preloader that I wrote with full callbacks, auto reading of images to preload, and a lot of easing in animations. Check it out here: jQuery Preloader
good sample of the plugin
[...] View Demo | Download Plugin [...]
I think your example would have been great, if you could change the image to make it appear more aesthetic rather than poor gif graphic (I presume it to be gif, don’t feel like going back to check it :)).
Point taken. I’ll swap out the default example image this week to something more suitable. Sometimes us developers get caught up in simply providing functionality with minimal consideration for aesthetics. I’ve definitely got to improve my examples a bit.