Usage
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.
Examples
Window resize
jQuery(window).on('resize', function(){
nebula.debounce(function(){
//This happens 500ms after the window stops resizing
}, 500, 'user resizing window');
});
Most optimal way to declare your debounce function
//Declare the function outside of the debounce and the event listener so that it is only created/stored in memory once.
const windowResizeDebounce = function(){
//This happens 500ms after the window stops resizing
};
jQuery(window).on('resize', function(){
nebula.debounce(windowResizeDebounce, 500, 'user resizing window'); //Then reference that function from within the event listener and debounce itself
});
User typing
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!
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
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 455.
No Hooks
This function does not have any filters or actions available. Request one?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. Remember: Some functionality is conditionally loaded via dynamic imports, so if your function is not overriding properly, try listening for a DOM event (described below).
For non-module import functions:
nebula.debounce = function(callback, wait, uniqueID, immediate){
//Write your own code here, leave it blank, or return false.
}
For dynamically imported module function overrides:
jQuery(window).on('load', function(){
nebula.debounce = function(callback, wait, uniqueID, immediate){
//Write your own code here, leave it blank, or return false.
}
});
Custom Nebula DOM events do also exist, so you could also try the following if the Window Load listener does not work:
jQuery(document).on('nebula_module_loaded', function(module){
//Note that the module variable is also available to know which module specifically was imported
if ( typeof nebula.debounce === 'function' ){
nebula.debounce = function(callback, wait, uniqueID, immediate){
//Write your own code here, leave it blank, or return false.
}
}
});