Spinners

Ask a question Design guidelines

Summary

Spinners are used for showing a system process of unknown length going on that ends with the system displaying results to the user.

Status

API status: general
Web resource key: com.atlassian.auiplugin:aui-spinner
AMD Module key: N/A
Experimental API: 5.1
General API: 5.8
Web Component API: 7.7

Examples

Normal spinner

AUI's spinner is just an HTML element. Add it to wherever you need to indicate progress is being made.

Demo code
Result
Small spinner
Medium spinner
Large spinner
​x
 
<h5>Small spinner</h5>
<aui-spinner size="small"></aui-spinner>
​
<h5>Medium spinner</h5>
<aui-spinner size="medium"></aui-spinner>
​
<h5>Large spinner</h5>
<aui-spinner size="large"></aui-spinner>

Spinners in buttons

Spinners are integrated in to AUI buttons for you.

You can use the busy() and idle() functions on a button to change the user's perception of a button as 'busy'.
Result
 
<button class="aui-button" id="button-spin-1">Do Something</button>
<button class="aui-button aui-button-primary" id="button-spin-2">Do Something</button>
 
AJS.$(document).on('click', '#button-spin-1, #button-spin-2', function() {
    var that = this;
    if (!that.isBusy()) {
        that.busy();
​
        setTimeout(function() {
            that.idle();
        }, 2000);
    }
});

Spinners in toggles

Spinners are integrated in to AUI toggles.

Demo code
Result
 
var form = document.getElementById('wifi-toggle-form');
form.addEventListener('change', function(e) {
    var toggle = document.getElementById('wifi-toggle');
    var isChecked = toggle.checked;     // new value of the toggle
    if (isChecked === false) { // do not call server if unchecked
        console.log("toggle is unchecked");
        return;
    }
    toggle.busy = true;
    $.post('set/my/variable', { value: isChecked })
        .done(function () {
            console.log('success');
        })
        .fail(function () {
            toggle.checked = !isChecked;
            console.error('display an error message');
        })
        .always(function () {
            toggle.busy = false;
        });
});

Positioning spinners inside other components

As a discrete HTML element, spinners can be positioned by adding CSS to the spinner's parent element.

Demo code
Result

Loading results...

 
<div id="search-area-example" class="custom-card-style">
    <p>Loading results...</p>
    <aui-spinner size="large"></aui-spinner>
</div>
 
#search-area-example {
    display: flex;
    flex-direction: column;
    align-items: center;
    justify-content: center;
}
​
#search-area-example aui-spinner {
    margin: 1em;
}
​
.custom-card-style {
    border-radius: 3px;
    box-shadow:
        0 1px 1px rgba(9, 30, 66, 0.25),
        0 0 1px 0 rgba(9, 30, 66, 0.31);
    margin: 0 auto;
    padding: 10px;
    width: 20em;
}
Demo code
Result
 
<nav class="aui-header" role="navigation" id="custom-spinner-example">
    <div class="aui-nav-secondary">
        <ul class="aui-nav">
            <li>
                <form class="aui-quicksearch" method="post" action="/foo">
                    <label class="assistive" for="quicksearchid">Text search</label>
                    <input type="text" name="quicksearchname" placeholder="Type to see a spinner" class="search" id="quicksearchid">
                </form>
            </li>
        </ul>
    </div>
</nav>
 
#custom-spinner-example .aui-quicksearch input {
    width: 20em;
}
#custom-spinner-example .aui-quicksearch.custom-quicksearch-indicator::after {
    display: none;
}
#custom-spinner-example .aui-quicksearch.custom-quicksearch-indicator aui-spinner {
    color: inherit;
    position: absolute;
    right: 20px;
}
 
(function() {
    var spinner = document.createElement('aui-spinner');
    spinner.setAttribute('size', 'small');
​
    function startSearching() {
        var $container = AJS.$('.aui-quicksearch');
        $container.addClass('custom-quicksearch-indicator');
        $container.append(spinner);
​
        return function stop() {
            $container.removeClass('custom-quicksearch-indicator');
            $container.find(spinner).remove();
        }
    }
​
    var searchTimeout = null;
    AJS.$(document).on('input', '#quicksearchid', function(e) {
        var stopSearching = startSearching();
        clearTimeout(searchTimeout);
        searchTimeout = setTimeout(stopSearching, 2000);
    });
​
    AJS.$(document).on('submit', '.aui-quicksearch', function(e) {
        e.preventDefault();
    });
}());

HTML API

<aui-spinner>
Name Attribute Property Type Default Description
size is an attribute is a property Enum medium An Enum which provides size of the spinner.
Possible values are: small(20px), medium(30px) and large(50px).
filled Deprecated is an attribute is a property Boolean false A Boolean which changes behavior of the spinner.
When present, the spinner element will be placed in the middle of the parent element and have a width and height of zero.

JavaScript API Deprecated

These functions are deprecated and only available via the com.atlassian.auiplugin:jquery-spin web-resource.

There are two jQuery functions available you can call on an element to add and remove a filled spinner.

Demo code
Result
 
<button class="aui-button" id="spinner-trigger">Do Something</button>
<span class="button-spinner" style="display: inline-block; height: 10px; width: 20px"></span>
 
AJS.$(function() {
    var spinning = false;
    AJS.$('#spinner-trigger').on('click', function() {
        if (!spinning) {
            AJS.$(this).text('Stop Spinning!');
            AJS.$('.button-spinner').spin();
            spinning = true;
        } else {
            AJS.$(this).text('Do Something');
            AJS.$('.button-spinner').spinStop();
            spinning = false;
        }
    });
});

Calling AJS.$(element).spin() will append the following spinner to element:

 
<aui-spinner size="small" filled></aui-spinner>

Calling AJS.$(element).spinStop() will remove the spinner element.