Skip to Content

debounce()

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

JavaScript February 7, 2021

Usage

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

Parameters

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

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

uniqueID
(Optional) (String) A unique ID to separate different Debounce function calls
Default: "No Unique ID"

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/modules/utilities.js on line 318.

No Hooks

This function does not have any filters or actions available. Request one?
JavaScript
nebula.debounce = function(callback = false, wait = 1000, uniqueID = 'No Unique ID', immediate = false){
    if ( !callback ){
        nebula.help('nebula.debounce() requires a callback function.', '/functions/debounce/');
        return false;
    }

    if ( typeof nebula.debounceTimers === 'undefined' ){
        nebula.debounceTimers = {};
    }

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

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