templating.returns

Render a full kida template.

Usage::

return Template("page.html", title="Home", items=items)

A template rendered from a string source. For prototyping.

Separate type so the content negotiation layer can distinguish it from file-based templates, andapp.check()can warn about inline templates in production code.

Render a named block from a kida template.

The target field controls how the fragment is delivered:

• OOB responses: target specifies the DOM element ID for the out-of-band swap. If target isNone(the default), the block name is used as the target ID.
• SSE streams: target becomes the SSE event name. Templates usesse-swap="{target}"to receive the fragment. If target isNone, the event name defaults to "fragment".

Usage::

return Fragment("search.html", "results_list", results=results)

With explicit OOB target::

Fragment("cart.html", "counter", target="cart-counter", count=5)

With explicit SSE event name::

yield Fragment("dashboard.html", "stats_panel",
               target="stats-update", stats=stats)
# Client: <div sse-swap="stats-update">

Render a full template or a named block, depending on the request.

Combines Template and Fragment semantics. The content negotiation layer inspects the incoming request headers and renders:

• Full template for normal browser navigations and htmx history-restore requests.
• Named block only for htmx fragment requests (HX-Request withoutHX-History-Restore-Request).

This eliminates the manualif request.is_fragmentboilerplate that every htmx-reachable route would otherwise need.

Usage::

return Page("hackernews.html", "story_list",
             stories=stories, page="list")

Represent a side-effect endpoint that should not swap response HTML.

Defaults to204 No Contentso htmx receives a successful response without replacing any target content. Optional htmx response headers can be attached for client-side behavior.

Usage::

return Action()
return Action(trigger="saved")
return Action(refresh=True)

Return a form fragment with 422 status for htmx validation.

Bundles the most common htmx form pattern: validate server-side, re-render the form fragment with errors on failure, return 422 so htmx knows to swap the error content.

The negotiation layer renders this as aFragmentwith status 422. If retarget is set, theHX-Retargetresponse header is added so htmx swaps errors into a different element than the original trigger.

Usage::

result = validate(form, rules)
if not result:
    return ValidationError("form.html", "form_body",
                           errors=result.errors, form=form)

With retarget::

return ValidationError("form.html", "form_errors",
                       retarget="#error-banner",
                       errors=result.errors)

Render a kida template with progressive streaming.

Context values that are awaitables resolve concurrently. Each template section streams to the browser as its data arrives.

Usage::

return Stream("dashboard.html",
    header=site_header(),
    stats=await load_stats(),
    feed=await load_feed(),
)

Render a page within a filesystem-based layout chain.

Used bymount_pages()routes. The negotiation layer composes the layout chain at the correct depth based onHX-Target:

• Full page load: render all layouts nested
• Boosted navigation: render from the targeted layout down
• Fragment request: render just the named block

The layout_chain and context_providers are set by the pages discovery system — handlers never construct this directly.

Usage (internal — set by the pages framework)::

return LayoutPage(
    "page.html", "content",
    layout_chain=chain,
    context_providers=providers,
    title="Home",
)

Compose a primary response with out-of-band fragment swaps.

htmx processes the first element as the normal swap target, then scans for elements withhx-swap-ooband swaps them into the page by ID.OOBrenders all fragments into a single HTML response with the correct attributes.

Each OOB fragment's target ID defaults to itsblock_name (convention), but can be overridden viaFragment(..., target="id").

Usage::

return OOB(
    Fragment("products.html", "list", products=products),
    Fragment("cart.html", "counter", count=new_count),
    Fragment("notifications.html", "badge", unread=3),
)

The first fragment is the primary swap target. All subsequent fragments are rendered withhx-swap-oob="true" and an id matching their target.