Spinner – A jQuery Preloader Plugin


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 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 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.

[sourcecode language=”javascript” light=”true”]
$(‘#example1’).click(function() {
var $this = $(this);
setTimeout(function() {
}, 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.

[sourcecode language=”javascript” light=”true”]
$(‘#example2’).click(function() {
var $this = $(this);
var opts = { position: ‘center’, hide: true };
setTimeout(function() {
}, 5000);
return false;

Example 3

The spinner is displayed to the left of multiple items that have a matching class for 2 seconds.

[sourcecode language=”javascript” light=”true”]
$(‘#example3’).click(function() {
var $this = $(‘.example3’);
var opts = { position: ‘left’ };
setTimeout(function() {
}, 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.

[sourcecode language=”javascript” light=”true”]
$(‘#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.’); }
setTimeout(function() {
}, 2000);
return false;


Downloads are currently available from the following sources:


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
  • jQueryNewBie

    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 :)).

    • cballou

      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.

  • Pingback: 25 Best And Useful jQuery Plugins of May 2010()

  • jshdjsdj

    good sample of the plugin

  • Edward Hotchkiss

    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

  • Ed

    Hi there

    Any hints on how to use this on a submit button?

    I can get the code working but the button does not submit!

    Many thanks

    • Corey Ballou

      Hey Ed,

      The default handling of Salid is to bind your actual form, i.e. $('form').salidate(options). If you take a look at the source code of the plugin, you’ll notice that Salid binds the target element to the submit event. If errors occur, the form will not be submitted due to handleErrors() function returning false. If no errors occur, the function should return true and the form submission should occur.

      If you have Firefox, I highly suggest you take a look at installing the Firebug plugin and turning it on when you are testing JavaScript code as it might be a quick indication of any errors occurring. Once you’ve got Firebug enabled, you’ll want to open it up and ensure the console tab is turned on.

      Let me know if this clears up anything for you, if not I’ll need to see your code to debug.

    • Ed

      Hi there Corey

      Thanks – I managed to get it working OK. It now displays a spinner when initiating a select, although I am hoping to modify this to spin until the select has completed (form submitted).

      For example I select the page “About the pentium III” from a dropdown and wish the spinner to continue until the (page load event?) of the selected page.

      I am using a onchange in the select to submit the form.

      I appreciate the code – this was actually very simple to use (firebug told me where my previous problem was… simply pointing to the wrong path to your .js!)


  • DStone

    This is a neat plugin, but I’m trying to get it to work with (fairly quick) AJAX calls of varying length, such that a setTimeout doesn’t seem to be the best solution. However, I’m pretty sure the spinner never shows up on my website is because the webpage never regains control to display the spinner before the AJAX call is done. Any suggestions?

    • LoRd

      @DStone: so you could use Jquerys “beforeSend” and “success”

      I used it like that (just a small example):
      type: "POST",
      dataType: "json",
      url: "myFile.php",
      data: jQuery.param($(‘formular’)),
      beforeSend: function(data){
      success: function(data){

      • Corey Ballou

        Also, just to be safe, you might want to add $this.spinner('remove'); to the error callback function.

  • jvrobert

    Hi – very small change – can you please add a ‘return;’ statement in the ‘if (options == ‘remove’ || options == ‘close’) {‘ block when ‘if (typeof $s != ‘undefined’) {‘ is false? Otherwise if you do a .(‘remove’) on a spinner that’s not currently showing, it starts showing.

  • Heyo

    Hi, thanx for this nice plugin.

    It’s working for me, but I got some serious browser issues.

    The image is not shown in Safari and Chrome. Those damn browser bugs!%$ยง

    Can anyone help me out here .. or anyone having the same issues?



  • Todd

    Very useful except I can’t figure out how to do this:
    I have an image I’m clicking on to load a page and when you click on the image the spinner shows which is perfect. The resulting page takes a bit to load so im thinking it would be handy to show something going on while it prepares to load.

    Problem is the url to the page doesn’t work any longer when you click the image. How do I get it to still go to the page the image is linked to??

    • Corey Ballou

      Hey Todd,
      In my examples I was using return false; which essentially prevents you from redirecting to a link. Simply removing this line will allow you to load your URL. Let me know if this helps.

  • Gerard


    I tried to use the spinner with a button that is in a dialog box. The spinner image appears, but hidden behind the dialog box. What should I do to display the spinner near the button, on top of the dialog box?

    Thank you!

    • Gerard

      I figured it out. The z-index of the dialog box was greater than the spinner’s default value.

      Great plugin ๐Ÿ˜‰