reactive.debounce
reactive.debounce(
delay_secs=MISSING,
fn_delay_secs=MISSING,
*,
priority=100,
session=MISSING,
)Wait for a reactive function to stop changing before invalidating its readers.
Every time the decorated function's reactive dependencies change, the timer starts over. Readers are invalidated only after delay_secs pass without another change. This is useful when only the final value matters (for example, while a user is typing) and the work that depends on it is slow.
With a 3-unit window, where each character is one unit of time and o is an invalidation:
source: ooo-oo-oo----
debounce: -----------o-
Parameters
fn :-
Only when called as
debounce(fn, delay_secs)instead of as a decorator: the no-argument function to limit, such as acalcor an input (input.text). delay_secs : Any = MISSING-
The number of seconds to wait after the last change. You may also pass a synchronous no-argument function or
calcthat returns the number of seconds, for example to let the user control the window. It must always return a number. If it stops early (for example withreq), the timer doesn’t start, and readers aren’t invalidated until it returns a number again. If it raises any other error, the session closes. priority : int = 100-
Debouncing is implemented with
effects. Use this argument to set their priority. It should be higher than the priority of the effects and outputs that read the debounced function (which default to 0). session : MISSING_TYPE | Session | None = MISSING-
A
Sessioninstance. If not provided, a session is inferred viaget_current_session.
Returns
Note
The decorated function may still run as often as before (or more often). Only the invalidation of its readers is slowed down, so use this when the decorated function is cheap and the work downstream of it is expensive.
Times are minimums: if the event loop is busy when the timer is due, the invalidation waits until it is free.
Tip
Like event, this decorator must be applied before @reactive.calc (i.e., @reactive.calc must be above it). It can’t be used with @reactive.effect or @render.xx, which have no value for readers to wait on: read the limited calc from them instead. An effect can react to it with @reactive.event(<calc>).
To limit a function you already have, such as an existing calc or an input, call it as debounce(fn, delay_secs). That returns a calc, so there’s no decorator to put in order.
See Also
Examples
#| standalone: true
#| components: [editor, viewer]
#| layout: vertical
#| viewerHeight: 400
## file: app.py
from shiny import App, Inputs, Outputs, Session, reactive, render, ui
app_ui = ui.page_fluid(
ui.input_text("text", "Type quickly"),
ui.output_text("raw"),
ui.output_text("debounced"),
)
def server(input: Inputs, output: Outputs, session: Session):
# Update only after typing stops for 1 second
@reactive.calc
@reactive.debounce(1)
def text_debounced():
return input.text()
@render.text
def raw():
return f"Raw: {input.text()}"
@render.text
def debounced():
return f"Debounced: {text_debounced()}"
app = App(app_ui, server)