Debounce

Debounce returns a formatted HTMX trigger string that adds a delay to an event. It is a convenience helper that ensures consistent delay:Xms changed trigger strings across your application.

Use Debounce with hx-trigger to debounce input events, preventing excessive server requests while the user is typing.

---

Quick Start

from faststrap import Debounce, Input

Input(
    placeholder="Search...",
    name="q",
    hx_get="/search",
    hx_target="#results",
    hx_trigger=Debounce(300),
)

---

Visual Examples & Use Cases

1. Default Debounce (300ms)

Debounce()
# Returns: "input changed delay:300ms"

2. Custom Delay

Debounce(delay=500)
# Returns: "input changed delay:500ms"

3. Custom Trigger Event

Debounce(trigger="keyup", event="keyup")
# Returns: "keyup changed delay:300ms"

4. Used with ActiveSearch

from faststrap import ActiveSearch

ActiveSearch(
    endpoint="/api/search",
    target="#results",
    debounce=500,
)
# Internally uses: hx-trigger="keyup changed delay:500ms"

---

Practical Functionality

1. Search Input with Debounce

from faststrap import Input

Input(
    type="search",
    placeholder="Search users...",
    name="q",
    hx_get="/api/users/search",
    hx_target="#user-list",
    hx_trigger=Debounce(300),
    cls="form-control",
)

2. Custom Debounce for Slow Endpoints

Input(
    placeholder="Type to search...",
    name="q",
    hx_get="/api/slow-search",
    hx_target="#results",
    hx_trigger=Debounce(800),
)

3. Debounce with Keyup Trigger

Input(
    placeholder="Filter...",
    name="filter",
    hx_get="/api/filter",
    hx_target="#results",
    hx_trigger=Debounce(200, trigger="keyup"),
)

---

Parameter Reference

Parameter	Type	Default	Description
delay	int	300	Milliseconds to wait after the event before sending the request.
trigger	str	"changed"	Base HTMX trigger event (e.g. "changed", "keyup").
event	str	"input"	Event to listen for (e.g. "input", "keyup").
**kwargs	Any	{}	Reserved for future extension.

---

Return Value

Debounce returns a string suitable for use with hx-trigger:

"{event} {trigger} delay:{delay}ms"

For example, Debounce(300) returns "input changed delay:300ms".

---

API Reference

faststrap.presets.interactions.Debounce(delay=300, *, trigger='changed', event='input', **kwargs)

Build a debounced HTMX trigger string.

Returns a formatted trigger string suitable for use with hx-trigger.

Parameters:

Name	Type	Description	Default
delay	int	Milliseconds to debounce.	300
trigger	str	Base HTMX trigger event (e.g. "changed", "keyup").	'changed'
event	str	Event to listen for (e.g. "input", "keyup").	'input'
**kwargs	Any	Reserved for future extension.	{}

Returns:

Type	Description
str	Formatted trigger string like "input changed delay:300ms".

Examples:

>>> Debounce(300)
'input changed delay:300ms'

>>> Debounce(500, trigger="keyup", event="keyup")
'keyup changed delay:500ms'

Source code in src/faststrap/presets/interactions.py

def Debounce(
    delay: int = 300,
    *,
    trigger: str = "changed",
    event: str = "input",
    **kwargs: Any,
) -> str:
    """Build a debounced HTMX trigger string.

    Returns a formatted trigger string suitable for use with `hx-trigger`.

    Args:
        delay: Milliseconds to debounce.
        trigger: Base HTMX trigger event (e.g. "changed", "keyup").
        event: Event to listen for (e.g. "input", "keyup").
        **kwargs: Reserved for future extension.

    Returns:
        Formatted trigger string like "input changed delay:300ms".

    Examples:
        >>> Debounce(300)
        'input changed delay:300ms'

        >>> Debounce(500, trigger="keyup", event="keyup")
        'keyup changed delay:500ms'
    """
    return f"{event} {trigger} delay:{delay}ms"