How to Throttle Bokeh Slider on_change Callback: Managing Rapid Update Requests During Sliding to Capture Final Value on Mouse Release

Table of Contents#

1. Understanding the Problem: Rapid Slider Events
2. Why Throttle/Debounce? The Cost of Uncontrolled Callbacks
3. Throttling vs. Debouncing: Which to Use?
4. Implementing Throttling/Debouncing in Bokeh
   • 4.1 Client-Side Debouncing with CustomJS (Static Apps)
   • 4.2 Server-Side Debouncing with Python (Bokeh Server)
5. Step-by-Step Example: Building a Debounced Slider App
6. Advanced Considerations
7. Conclusion
8. References

1. Understanding the Problem: Rapid Slider Events#

To grasp why slider callbacks need throttling, let’s first examine how Bokeh sliders work. When a user clicks and drags a slider, the slider’s value property updates continuously with every small movement of the mouse. Each update triggers the on_change callback function associated with the slider.

For example, if a user drags a slider from 0 to 100, the slider might fire 50–100 on_change events (depending on mouse sensitivity). If your callback performs heavy operations—like querying a database, rendering a large plot, or running a machine learning model—this cascade of events can:

• Slow down the app (visible lag).
• Overload the server (wasted CPU/memory).
• Frustrate users (stuttering UI).

In most cases, you don’t need to process every intermediate slider value—only the final value when the user releases the mouse. The goal is to “ignore” intermediate events and trigger the callback only after sliding stops.

2. Why Throttle/Debounce? The Cost of Uncontrolled Callbacks#

Unthrottled slider callbacks can degrade app performance in subtle and not-so-subtle ways:

Throttling or debouncing ensures the callback runs only when necessary, mitigating these issues.

3. Throttling vs. Debouncing: Which to Use?#

Before implementing a solution, it’s critical to distinguish between two common rate-limiting techniques: throttling and debouncing.

Throttling#

• Definition: Limits the callback to run at most once every X milliseconds during continuous events.
• Use Case: Useful when you need updates at a steady rate (e.g., updating a progress bar every 100ms during sliding).

Debouncing#

• Definition: Delays the callback until X milliseconds of inactivity after the last event. If a new event occurs before X ms, the timer resets.
• Use Case: Ideal for capturing the final value after sliding stops (e.g., updating a plot only when the user releases the mouse).

For our goal—capturing the final slider value—debouncing is the right tool. It ensures the callback runs only after the user stops sliding (i.e., when no new value updates occur for X ms).

4. Implementing Throttling/Debouncing in Bokeh#

Bokeh supports two deployment modes: static apps (HTML/JS files) and Bokeh Server apps (dynamic, server-backed apps). We’ll cover debouncing for both.

4.1 Client-Side Debouncing with CustomJS (Static Apps)#

For static Bokeh apps (no server), use CustomJS to implement debouncing directly in the browser (client-side). This avoids server round-trips and is lightweight.

How it works:

• Use JavaScript’s setTimeout to delay the callback.
• Use clearTimeout to reset the timer on each new slider event.
• The callback runs only if X ms pass without new events (i.e., after sliding stops).

4.2 Server-Side Debouncing with Python (Bokeh Server)#

For Bokeh Server apps (where callbacks run on the server), use Python’s threading.Timer or asyncio to debounce. This is useful if your callback depends on server-side logic (e.g., accessing a database).

How it works:

• Track the current timer with a variable.
• On each slider event, cancel the existing timer (if any) and start a new one.
• The callback runs only if no new events occur before the timer expires.

5. Step-by-Step Example: Building a Debounced Slider App#

Let’s walk through building a simple app with a debounced slider. We’ll cover both static (CustomJS) and server-side (Python) approaches.

5.1 Prerequisites#

• Bokeh installed: pip install bokeh
• Basic familiarity with Bokeh widgets and callbacks.

5.2 Static App: Client-Side Debouncing with CustomJS#

This example creates a static HTML app where the slider’s callback is debounced using JavaScript. The app will log the final slider value to the browser’s console after sliding stops.

Step 1: Import Bokeh Libraries#

from bokeh.plotting import figure, show
from bokeh.models import Slider, CustomJS
from bokeh.layouts import column

Step 2: Define the Slider and Plot#

We’ll use a simple plot to visualize the slider’s effect (e.g., adjusting the height of a bar).

# Create a plot
p = figure(plot_width=400, plot_height=300, y_range=(0, 100))
bar = p.vbar(x=1, top=50, width=0.5, color="navy")  # Initial bar height
 
# Create a slider (0–100, initial value 50)
slider = Slider(
    start=0, 
    end=100, 
    value=50, 
    step=1, 
    title="Adjust Bar Height"
)

Step 3: Add Debounced CustomJS Callback#

Use CustomJS to add client-side debouncing. We’ll store the timeout ID in the browser’s window object to reset it on each slider event.

debounce_delay = 500  # Debounce delay in milliseconds (adjust as needed)
 
callback = CustomJS(
    args=dict(slider=slider, bar=bar),
    code="""
    // Clear the previous timeout (if it exists)
    if (window.sliderTimeout) {
        clearTimeout(window.sliderTimeout);
    }
 
    // Set a new timeout to run after debounce_delay ms of inactivity
    window.sliderTimeout = setTimeout(() => {
        // Update the bar height with the final slider value
        const finalValue = slider.value;
        bar.data_source.data.top = [finalValue];
        bar.data_source.change.emit();  // Trigger plot update
        
        // Log to console (for demonstration)
        console.log(`Final slider value: ${finalValue}`);
    }, %d);  // Inject debounce_delay from Python
    """ % debounce_delay
)
 
# Attach the callback to the slider's 'value' property
slider.js_on_change('value', callback)

Step 4: Assemble and Show the App#

# Arrange widgets in a column
layout = column(slider, p)
 
# Save or show the app
show(layout)

How It Works:#

• When the user drags the slider, js_on_change fires, but setTimeout delays the actual update.
• If the user continues sliding, clearTimeout resets the timer, preventing intermediate updates.
• Only when the user stops sliding for debounce_delay (500ms), the callback runs, updating the bar and logging the final value.

5.3 Bokeh Server App: Server-Side Debouncing with Python#

For apps requiring server-side logic (e.g., fetching data from a server database), use Python’s threading.Timer to debounce.

Step 1: Import Libraries and Set Up the Server#

from bokeh.server.server import Server
from bokeh.application import Application
from bokeh.application.handlers.function import FunctionHandler
from bokeh.plotting import figure, curdoc
from bokeh.models import Slider
from bokeh.layouts import column
import threading

Step 2: Define the Debounced Callback#

We’ll use a threading.Timer to delay the callback. A nonlocal variable tracks the current timer, which is canceled and restarted on each slider event.

def modify_doc(doc):
    # Create a plot and slider
    p = figure(plot_width=400, plot_height=300, y_range=(0, 100))
    bar = p.vbar(x=1, top=50, width=0.5, color="firebrick")
    slider = Slider(start=0, end=100, value=50, title="Adjust Bar Height")
 
    # Track the current debounce timer
    debounce_timer = None
    debounce_delay = 500  # ms
 
    def final_callback(value):
        """Server-side logic to run after debouncing (e.g., fetch data, process, update plot)."""
        print(f"[Server] Final slider value: {value}")  # Simulate server work (e.g., DB query)
        bar.data_source.data.top = [value]  # Update the plot
 
    def on_slider_change(attr, old, new):
        """Handler for slider 'value' changes: cancels old timer and starts a new one."""
        nonlocal debounce_timer
        # Cancel existing timer (if any)
        if debounce_timer is not None:
            debounce_timer.cancel()
        # Start a new timer to run final_callback after debounce_delay
        debounce_timer = threading.Timer(debounce_delay / 1000, final_callback, args=[new])
        debounce_timer.start()
 
    # Attach the slider callback
    slider.on_change('value', on_slider_change)
    doc.add_root(column(slider, p))
 
# Run the Bokeh Server
app = Application(FunctionHandler(modify_doc))
server = Server({'/': app})
server.start()
print(f"Server running at http://localhost:{server.port}")
server.io_loop.add_callback(server.show, "/")
server.io_loop.start()

How It Works:#

• When the slider moves, on_slider_change cancels the existing debounce_timer and starts a new one.
• If the user stops sliding for debounce_delay (500ms), final_callback runs, executing server-side logic (e.g., querying a database) and updating the plot.

6. Advanced Considerations#

Adjusting the Debounce Delay#

The optimal debounce_delay (typically 300–1000ms) depends on user behavior:

• Shorter delays (300ms): Faster response but risk of intermediate updates.
• Longer delays (1000ms): Safer but feels slower to users.
  Test with real users to find the sweet spot.

Handling Multiple Sliders#

For apps with multiple sliders, use unique timer IDs to avoid cross-talk:

• In CustomJS: Use window.slider1Timeout, window.slider2Timeout, etc.
• In Python: Use a dictionary to track timers per slider (e.g., timers = {"slider1": None, "slider2": None}).

Combining with Immediate Feedback#

For apps where users need some immediate feedback (e.g., a preview), combine debouncing with lightweight intermediate updates. For example:

• Use a fast client-side callback to update a small preview (no debounce).
• Use a debounced server-side callback to update the full dataset (with debounce).

Avoiding Memory Leaks#

• In CustomJS: Always clear timeouts to prevent orphaned timers.
• In Python/Bokeh Server: Cancel timers when the app is closed (use curdoc().on_session_destroyed).

7. Conclusion#

Throttling or debouncing Bokeh slider callbacks is critical for building responsive, efficient apps. By delaying callbacks until sliding stops, you reduce unnecessary computations, network traffic, and UI lag.

• For static apps: Use CustomJS with setTimeout/clearTimeout for client-side debouncing.
• For Bokeh Server apps: Use threading.Timer to debounce server-side logic.

With these techniques, you can ensure your sliders feel smooth and responsive while keeping your app performant.

8. References#

• Bokeh Slider Documentation
• Bokeh CustomJS Guide
• Bokeh Server Documentation
• MDN Web Docs: setTimeout
• Python threading.Timer Documentation
• Debouncing vs. Throttling: CSS-Tricks