SwapOnEvent

SwapOnEvent renders a container that listens for a custom DOM event and triggers an HTMX swap. This is useful for coordinating UI updates from non-HTMX JavaScript code without coupling directly to HTMX internals.

Use Case

Use SwapOnEvent when you need to trigger an HTMX swap from a custom event dispatched by another script, a WebSocket message, or a browser API.

---

Quick Start

from faststrap import SwapOnEvent

SwapOnEvent(
    "Loading...",
    event_name="data:updated",
    target="#results",
    swap="innerHTML",
)

---

Visual Examples & Use Cases

1. Basic Swap on Custom Event

SwapOnEvent(
    "Initial content",
    event_name="my:update",
    target="#results",
    swap="innerHTML",
)

Trigger with JavaScript:

document.dispatchEvent(new CustomEvent("my:update"));

2. Custom Swap Strategy

SwapOnEvent(
    "<p>Replacement content</p>",
    event_name="refresh",
    target="this",
    swap="outerHTML",
)

3. With HTMX Endpoint

Set a data attribute to specify the endpoint:

SwapOnEvent(
    "Loading...",
    event_name="refresh",
    target="#content",
    swap="innerHTML",
    data_fs_swap_endpoint="/api/content",
)

Then the JS runtime will call htmx.ajax('GET', '/api/content', { target: '#content', swap: 'innerHTML' }).

---

Practical Functionality

1. WebSocket-Driven Updates

from faststrap import SwapOnEvent

SwapOnEvent(
    "Waiting for updates...",
    event_name="ws:message",
    target="#live-feed",
    swap="beforeend",
)

// In your WebSocket handler:
ws.onmessage = (event) => {
    document.dispatchEvent(new CustomEvent("ws:message", {
        detail: { data: event.data }
    }));
};

2. Browser API Integration

SwapOnEvent(
    "Geolocation not set",
    event_name="faststrap:location:success",
    target="#location-display",
    swap="innerHTML",
    data_fs_swap_endpoint="/update-location",
)

3. Event-Driven Refresh

SwapOnEvent(
    "Click refresh to update",
    event_name="manual-refresh",
    target="this",
    swap="innerHTML",
)

// Trigger from console or another script:
document.dispatchEvent(new CustomEvent("manual-refresh"));

---

Parameter Reference

Parameter	Type	Default	Description
*children	Any	required	Initial content to show before the swap.
event_name	str	"faststrap:swap"	Custom event name to listen for.
target	str	"this"	HTMX swap target selector.
swap	str	"innerHTML"	HTMX swap strategy (innerHTML, outerHTML, beforeend, etc.).
**kwargs	Any	{}	Additional HTML attributes.

---

API Reference

faststrap.presets.interactions.SwapOnEvent(*children, event_name='faststrap:swap', target='this', swap='innerHTML', **kwargs)

Trigger an HTMX swap from a custom client event.

Useful for coordinating UI updates from non-HTMX JavaScript code without coupling directly to HTMX internals.

Parameters:

Name	Type	Description	Default
*children	Any	Initial content to show before the swap.	()
event_name	str	Custom event name to listen for.	'faststrap:swap'
target	str	HTMX swap target selector.	'this'
swap	str	HTMX swap strategy (innerHTML, outerHTML, etc.).	'innerHTML'
**kwargs	Any	Additional HTML attributes for the container.	{}

Returns:

Type	Description
Div	FastHTML Div element that swaps on the custom event.

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

def SwapOnEvent(
    *children: Any,
    event_name: str = "faststrap:swap",
    target: str = "this",
    swap: str = "innerHTML",
    **kwargs: Any,
) -> Div:
    """Trigger an HTMX swap from a custom client event.

    Useful for coordinating UI updates from non-HTMX JavaScript code
    without coupling directly to HTMX internals.

    Args:
        *children: Initial content to show before the swap.
        event_name: Custom event name to listen for.
        target: HTMX swap target selector.
        swap: HTMX swap strategy (innerHTML, outerHTML, etc.).
        **kwargs: Additional HTML attributes for the container.

    Returns:
        FastHTML Div element that swaps on the custom event.
    """
    user_cls = kwargs.pop("cls", "")
    all_classes = merge_classes("faststrap-swap-on-event", user_cls)

    attrs: dict[str, Any] = {
        "cls": all_classes,
        "data_fs_swap_event": event_name,
        "data_fs_swap_target": target,
        "data_fs_swap": swap,
    }
    attrs.update(convert_attrs(kwargs))
    return Div(*children, **attrs)