jQuery throttle / debounce: Sometimes, less is more!

Version: 1.0, Last updated: 3/6/2010

Project Homehttp://benalman.com/projects/jquery-throttle-plugin/
GitHubhttp://github.com/cowboy/jquery-throttle/
Sourcehttp://github.com/cowboy/jquery-throttle/raw/master/jquery.ba-throttle.js
(Minified)http://github.com/cowboy/jquery-throttle/raw/master/jquery.ba-throttle.min.js (0.6kb)
Summary
jQuery throttle / debounce: Sometimes, less is more!Version: 1.0, Last updated: 3/6/2010
LicenseCopyright © 2010 “Cowboy” Ben Alman, Dual licensed under the MIT and GPL licenses.
ExamplesThese working examples, complete with fully commented code, illustrate a few ways in which this plugin can be used.
Support and TestingInformation about what version or versions of jQuery this plugin has been tested with and what browsers it has been tested in.
Release History
Note for non-jQuery usersjQuery isn’t actually required for this plugin, because nothing internal uses any jQuery methods or properties.
Functions
jQuery.throttleThrottle execution of a function.
jQuery.debounceDebounce execution of a function.

License

Copyright © 2010 “Cowboy” Ben Alman, Dual licensed under the MIT and GPL licenses.  http://benalman.com/about/license/

Examples

These working examples, complete with fully commented code, illustrate a few ways in which this plugin can be used.

Throttlehttp://benalman.com/code/projects/jquery-throttle/examples/throttle/
Debouncehttp://benalman.com/code/projects/jquery-throttle/examples/debounce/

Support and Testing

Information about what version or versions of jQuery this plugin has been tested with and what browsers it has been tested in.

jQuery Versions1.3.2, 1.4.2
Browsers TestedInternet Explorer 6-8, Firefox 2-3.6, Safari 3-4, Chrome 4-5, Opera 9.6-10.1.

Release History

1.0(3/3/2010) Initial release as a stand-alone project.  Migrated over from jquery-misc repo v0.4 to jquery-throttle repo v1.0.

Note for non-jQuery users

jQuery isn’t actually required for this plugin, because nothing internal uses any jQuery methods or properties. jQuery is just used as a namespace under which these methods can exist.

Since jQuery isn’t actually required for this plugin, if jQuery doesn’t exist when this plugin is loaded, the method described below will be created in the `Cowboy` namespace.  Usage will be exactly the same, but instead of $.method() or jQuery.method(), you’ll need to use Cowboy.method().

Functions

jQuery.throttle

Throttle execution of a function.  Especially useful for rate limiting execution of handlers on events like resize and scroll.  If you want to rate-limit execution of a function to a single time, see the jQuery.debounce method.

In this visualization, | is a debounced-function call and X is the actual callback execution:

Throttled with `no_trailing` specified as false or unspecified:
||||||||||||||||||||||||| (pause) |||||||||||||||||||||||||
X    X    X    X    X    X        X    X    X    X    X    X

Throttled with `no_trailing` specified as true:
||||||||||||||||||||||||| (pause) |||||||||||||||||||||||||
X    X    X    X    X             X    X    X    X    X

Usage

var throttled = jQuery.throttle( delay, [ no_trailing, ] callback );

jQuery('selector').bind( 'someevent', throttled );
jQuery('selector').unbind( 'someevent', throttled );

This also works in jQuery 1.4+

jQuery('selector').bind( 'someevent', jQuery.throttle( delay, [ no_trailing, ] callback ) );
jQuery('selector').unbind( 'someevent', callback );

Arguments

delay(Number) A zero-or-greater delay in milliseconds after which callback will be executed.  For event callbacks, values around 100 or 250 (or even higher) are most useful.
no_trailing(Boolean) Optional, defaults to false.  If no_trailing is true, callback will only execute every `delay` milliseconds while the throttled-function is being called.  If no_trailing is false or unspecified, callback will be executed one final time after the last throttled-function call.  (After the throttled-function has not been called for `delay` milliseconds, the internal counter is reset)
callback(Function) A function to be executed after delay milliseconds.

Returns

(Function) A new, throttled, function.

jQuery.debounce

Debounce execution of a function.  Debouncing, unlike throttling, guarantees that a function is only executed a single time, either at the very beginning of a series of calls, or at the very end.  If you want to simply rate-limit execution of a function, see the jQuery.throttle method.

In this visualization, | is a debounced-function call and X is the actual callback execution:

Debounced with `at_begin` specified as false or unspecified:
||||||||||||||||||||||||| (pause) |||||||||||||||||||||||||
                         X                                 X

Debounced with `at_begin` specified as true:
||||||||||||||||||||||||| (pause) |||||||||||||||||||||||||
X                                 X

Usage

var debounced = jQuery.debounce( delay, [ at_begin, ] callback );

jQuery('selector').bind( 'someevent', debounced );
jQuery('selector').unbind( 'someevent', debounced );

This also works in jQuery 1.4+

jQuery('selector').bind( 'someevent', jQuery.debounce( delay, [ at_begin, ] callback ) );
jQuery('selector').unbind( 'someevent', callback );

Arguments

delay(Number) A zero-or-greater delay in milliseconds.
at_begin(Boolean) Optional, defaults to false.  If at_begin is false or unspecified, callback will only be executed `delay` milliseconds after the last debounced-function call.  If at_begin is true, callback will be executed only at the first debounced-function call.  (After the throttled-function has not been called for `delay` milliseconds, the internal counter is reset)
callback(Function) A function to be executed after delay milliseconds.

Returns

(Function) A new, debounce, function.

Debounce execution of a function.
Throttle execution of a function.
Close