SSETarget

SSETarget connects a DOM container to an SSE endpoint and updates it as events arrive.

---

Quick Start

Live Preview

Waiting for updates...

from faststrap import SSETarget

SSETarget(
    "Waiting for updates...",
    endpoint="/api/stream",
    swap="inner",
)

---

Swap Modes

Valid values:

• inner
• outer
• before
• after
• append
• prepend
• replace
• text

Use text if you want to update plain text only.

---

Targeting Another Element

SSETarget(
    "",
    endpoint="/api/stream",
    target="#status",
    swap="text",
)

---

Connection Options

SSETarget(
    "Live",
    endpoint="/api/stream",
    event="message",
    with_credentials=True,
    reconnect=True,
    retry=3000,
)

Use retry to suggest a reconnection delay (milliseconds). For swap="outer" or swap="replace", stream a single root element so the target can be rebound safely after replacement.

---

Pair With SSEStream

from faststrap.presets import SSEStream, sse_event

@app.get("/api/stream")
async def stream():
    async def gen():
        yield sse_event("Hello")
    return SSEStream(gen())

---

Accessibility

SSETarget sets aria-live="polite" by default. Set aria_live=None to disable the live region.

---

Security Notes

Protect your SSE endpoints with auth and rate limits. Do not stream sensitive data to unauthenticated clients. If you stream HTML fragments, treat them as trusted server-rendered content.

---

API Reference

faststrap.components.display.sse_target.SSETarget(*children, endpoint, event='message', swap='inner', target=None, with_credentials=False, reconnect=True, retry=None, aria_live='polite', content=None, **kwargs)

Client-side SSE target that updates when new events arrive.

Parameters:

Name	Type	Description	Default
*children	Any	Initial content to render inside the target.	()
endpoint	str	SSE endpoint URL (must return text/event-stream).	required
event	str	SSE event name to listen for (default: "message").	'message'
swap	SSESwapType	How to apply incoming data ("inner", "outer", "append", "text", etc.).	'inner'
target	str | None	Optional CSS selector for a separate element to update.	None
with_credentials	bool	Use cookies/credentials with EventSource.	False
reconnect	bool	Whether to allow automatic reconnect (default: True).	True
retry	int | None	Optional reconnect delay hint (milliseconds).	None
aria_live	str | None	ARIA live region value (default: "polite").	'polite'
content	Any | None	Optional alternative to *children for initial content.	None
**kwargs	Any	Additional HTML attributes.	{}

Source code in src/faststrap/components/display/sse_target.py

@register(category="display", requires_js=True)
@beta
def SSETarget(
    *children: Any,
    endpoint: str,
    event: str = "message",
    swap: SSESwapType = "inner",
    target: str | None = None,
    with_credentials: bool = False,
    reconnect: bool = True,
    retry: int | None = None,
    aria_live: str | None = "polite",
    content: Any | None = None,
    **kwargs: Any,
) -> Div:
    """Client-side SSE target that updates when new events arrive.

    Args:
        *children: Initial content to render inside the target.
        endpoint: SSE endpoint URL (must return text/event-stream).
        event: SSE event name to listen for (default: "message").
        swap: How to apply incoming data ("inner", "outer", "append", "text", etc.).
        target: Optional CSS selector for a separate element to update.
        with_credentials: Use cookies/credentials with EventSource.
        reconnect: Whether to allow automatic reconnect (default: True).
        retry: Optional reconnect delay hint (milliseconds).
        aria_live: ARIA live region value (default: "polite").
        content: Optional alternative to *children for initial content.
        **kwargs: Additional HTML attributes.
    """
    cfg = resolve_defaults(
        "SSETarget",
        event=event,
        swap=swap,
        with_credentials=with_credentials,
        reconnect=reconnect,
        retry=retry,
        aria_live=aria_live,
    )

    c_event = cfg.get("event", event)
    c_swap = cfg.get("swap", swap)
    c_with_credentials = cfg.get("with_credentials", with_credentials)
    c_reconnect = cfg.get("reconnect", reconnect)
    c_retry = cfg.get("retry", retry)
    c_aria_live = cfg.get("aria_live", aria_live)

    if content is not None and not children:
        children = (content,)

    user_cls = kwargs.pop("cls", "")
    cls = merge_classes("faststrap-sse-target", user_cls)

    attrs: dict[str, Any] = {
        "cls": cls,
        "data_fs_sse": "true",
        "data_fs_sse_endpoint": endpoint,
        "data_fs_sse_event": c_event,
        "data_fs_sse_swap": c_swap,
    }

    if target:
        attrs["data_fs_sse_target"] = target
    if c_with_credentials:
        attrs["data_fs_sse_credentials"] = "true"
    if not c_reconnect:
        attrs["data_fs_sse_reconnect"] = "false"
    if c_retry is not None:
        attrs["data_fs_sse_retry"] = str(c_retry)
    if c_aria_live:
        attrs["aria_live"] = c_aria_live

    attrs.update(convert_attrs(kwargs))

    return Div(*children, **attrs)