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 a calc or 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 calc that 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 with req), 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 Session instance. If not provided, a session is inferred via get_current_session.

Returns

: Any

A decorator for a no-argument function (regular or async). The result returns the decorated function’s value, but its readers are invalidated only after the changes stop. Called as (fn, delay_secs), it returns a calc that does the same for fn.

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)