Skip to Content

debounce()

Waits for a series of similar events to finish before triggering.

JavaScript June 30, 2020

Usage

JavaScript
nebula.debounce(callback, wait, uniqueId, immediate)

Parameters

callback
(Required) (Function) The function to run after the wait period
Default: None

wait
(Required) (Integer) How long (in milliseconds) before the callback is ran
Default: None

uniqueID
(Optional) (String) A unique ID to separate different Debounce function calls
Default: "Don't call this twice without a uniqueId"

immediate
(Optional) (Boolean) Use this to trigger the callback on the leading edge
Default: false

Parameter Notes

If “immediate” is true, the callback function is triggered immediately and then not again until after the wait period has completed. Otherwise, the callback function happens after the wait period by default.

Request or provide clarification »

Examples

Window resize

JavaScript
jQuery(window).on('resize', function(){
    nebula.debounce(function(){
        //This happens 500ms after the window stops resizing
    }, 500, 'user resizing window');
});

User typing

JavaScript
jQuery('#s').keyup(function(){
    //Do something when the user begins typing...
    
    nebula.debounce(function(){
        //Do something when the user has stopped typing for 1.5 seconds...
    }, 1500, 'user typing in search');
});

Remember that the scope of "this" changes inside of the debounce function!

JavaScript
jQuery('#s').keyup(function(){
    var oThis = jQuery(this); //Store "this" in an object to pass into the debounce
    
    nebula.debounce(function(){
        //jQuery(this) now refers to the debounce function- not the input!
        var inputValue = oThis.val();
    }, 1500, 'user typing in search');
});

Demo


Global Click Test

Click This <p> Test

Click This <a> Test

Mouse Movement

Window Resize

Window Scroll

Additional Notes

Similar to throttle() but debounce only allows the callback once at the end (or the beginning) whereas throttle happens multiple times with a “cooldown” in between.

Source File

Located in /assets/js/nebula.js on line 3991.

JavaScript
nebula.debounce = function(callback, wait, uniqueID, immediate){
    if ( typeof nebula.debounceTimers === "undefined" ){
        nebula.debounceTimers = {};
    }

    if ( !uniqueID ){
        uniqueID = "Don't call this twice without a uniqueID";
    }

    var context = this;
    var args = arguments;
    var later = function(){
        nebula.debounceTimers[uniqueID] = null;
        if ( !immediate ){
            callback.apply(context, args);
        }
    };
    var callNow = immediate && !nebula.debounceTimers[uniqueID];

    clearTimeout(nebula.debounceTimers[uniqueID]); //Clear the timeout on every event. Once events stop the timeout is allowed to complete.
    nebula.debounceTimers[uniqueID] = setTimeout(later, wait);
    if ( callNow ){
        callback.apply(context, args);
    }
};

Override

To override or disable this JavaScript function, simply redeclare it with the exact same function name.

JavaScript
nebula.debounce = function(callback, wait, uniqueID, immediate){
    //Write your own code here, leave it blank, or return false.
}