Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Easily add spinners or general request tracking to your angular app
Latest commit dc848e4 @ajoslin release(): v2.1.0


Version: 2.0

(note to users using version 1.x: upgrading has many breaking changes, see the CHANGELOG.)

Build Status

Small, feature filled library used to easily add spinners or general promise/request tracking to your angular app.

Quick Start

The basic idea: each time we add one or more promises to an instance of a promiseTracker, that instance's active() method will return true until all added promises are resolved. A common use case is showing some sort of loading spinner while some http requests are loading.

Play with this example on plunkr

$ bower install angular-promise-tracker
<body ng-app="myApp" ng-controller="MainCtrl">
  <div class="my-super-awesome-loading-box" ng-show="">
  <button ng-click="delaySomething()">Delay Something</button>
  <button ng-click="fetchSomething()">Fetch Something</button>

  <script src="angular.js"></script>
  <script src="promise-tracker.js"></script>

  <!-- optional for $http sugar -->
  <script src="promise-tracker-http-interceptor.js"></script>
angular.module('myApp', ['ajoslin.promise-tracker'])
.controller('MainCtrl', function($scope, $http, $timeout, promiseTracker) {
  //Create a new tracker
  $scope.loadingTracker = promiseTracker();

  //use `addPromise` to add any old promise to our tracker
  $scope.delaySomething = function() {
    var promise = $timeout(function() {
      alert('Delayed something!');
    }, 1000);

  //use `tracker:` shortcut in $http config to link our http promise to a tracker
  //This shortcut is included in promise-tracker-http-interceptor.js
  $scope.fetchSomething = function(id) {
    return $http.get('/something', {
      tracker: $scope.loadingTracker
    }).then(function(response) {
      alert('Fetched something! ' +;

API Documentation

Service promiseTracker

  • tracker promiseTracker([options])

    Creates and returns a new promiseTracker.

    Options can be given as an object, with the following allowed values:

    • activationDelay {Number} - Number of milliseconds that an added promise needs to be pending before this tracker is active.
      • Usage example: You have some http calls that sometimes return too quickly for a loading spinner to look good. You only want to show the tracker if a promise is pending for over 500ms. You put {activationDelay: 500} in options.
    • minDuration {Number} - Minimum number of milliseconds that a tracker will stay active.
      • Usage example: You want a loading spinner to always show up for at least 750ms. You put {minDuration: 750} in options.

    Often you want a global promiseTracker (eg to show a loading screen); one easy way is to put the tracker on your $rootScope:$rootScope, promiseTracker) {
      $rootScope.loadingTracker = promiseTracker();

Instantiated promiseTracker

Example: var myTracker = promiseTracker({ activationDelay: 500, minDuration: 750 });

  • boolean

    Returns whether this tracker is currently active. That is, whether any of the promises added to/created by this tracker are still pending. Note: if the activationDelay has not elapsed yet, this will return false.

  • boolean tracker.tracking()

    Returns whether this tracker is currently tracking a request. That is, whether any of the promises added to/created by this tracker are still pending. This method has no regard for activationDelay.

  • void tracker.addPromise(promise)

    Add any arbitrary promise to tracker. will be true until promise is resolved or rejected.

    • promise {object} - Promise to add

    Usage Example:

    var promise = $timeout(doSomethingCool, 1000);
    console.log(; // => true
    //1000 milliseconds later...
    console.log(; // => false
  • promise tracker.createPromise()

    Creates and returns a new deferred object that is tracked by our promiseTracker.

    Usage Example:

    var deferred = myTracker.createPromise()
    console.log(; // => true
    console.log(; // => false
  • void tracker.cancel()

    Causes a tracker to immediately become inactive and stop tracking all current promises.

$http Sugar

Requires promise-tracker-http-interceptor.js

  • Any $http call's config parameter can have a tracker field. Examples:

    //Add $http promise to tracker with id 'myTracker'
    $http('/banana', { tracker: myPromiseTrackerInstance })
    //Add $http promise to both 'tracker1' and 'tracker2'
    $'/elephant', {some: 'data'}, { tracker: [myFirstTracker, mySecondTracker] })

More Examples

  • Do something whenever the tracker's active state changes
angular.module('app', ['ajoslin.promise-tracker'])

.factory('myTracker', function (promiseTracker) {
  return promiseTracker();

.controller('AppCtrl', function ($rootScope, myTracker) {
  $rootScope.$watch(, function (isActive) {


  • Install karma & grunt with npm install -g karma grunt-cli to build & test
  • Install local dependencies with bower install && npm install
  • Run grunt to lint, test, build the code, and build the docs site
  • Run grunt dev to watch and re-test on changes

New Versions


Public Domain Mark angular-promise-tracker by Andy Joslin is free of known copyright restrictions.

Something went wrong with that request. Please try again.