asgi-htmx

HTMX integration for ASGI applications. Works with Starlette, FastAPI, Quart — or any other web framework supporting ASGI that exposes the ASGI scope. Inspired by django-htmx.

Installation

Not on PyPI yet. For now, try asgi-htmx out by installing from git:

pip install git+https://github.com/florimondmanca/asgi-htmx.git

Quickstart

First, ensure HTMX is installed.

For example, download a copy of htmx.min.js, add it to your static files, then add the script tag to templates:

<script src="{{ url_for('static', path='/js/htmx.min.js') }}" defer></script>

Now, install HtmxMiddleware onto the ASGI app:

  • Using Starlette:

    from asgi_htmx import HtmxMiddleware
from starlette.middleware import Middleware

app = Starlette(
    middleware=[
        ...,
        Middleware(HtmxMiddleware),
        ...,
    ],
)

  • Using FastAPI:

    from asgi_htmx import HtmxMiddleware
from fastapi import FastAPI

app = FastAPI()
app.add_middleware(HtmxMiddleware)

You can now access scope["htmx"] (an instance of HtmxDetails) in endpoints:

# `HtmxRequest` makes code editors type-check `request.scope["htmx"]`
from asgi_htmx import HtmxRequest as Request

from .resources import templates

async def home(request: Request):
    template = "home.html"
    context = {"request": request}

    if (htmx := request.scope["htmx"]):
        template = "partials/items.html"
        context["boosted"] = htmx.boosted  # ...

    return templates.TemplateResponse(template, context)

See examples for full working example code.

API Reference

HtmxMiddleware

An ASGI middleware that sets scope["htmx"] to an instance of HtmxDetails (scope refers to the ASGI scope).

app = HtmxMiddleware(app)

HtmxDetails

A helper that provides shortcuts for accessing HTMX-specific request headers.

htmx = HtmxDetails(scope)
  • __bool__() -> bool – Return True if the request was made using HTMX (HX-Request is present), False otherwise.
  • boosted: bool – Mirrors the HX-Boosted header: True if the request is via an element with the hx-boost attribute.
  • current_url: str | None – Mirrors the HX-Current-URL header: The current URL of the browser, or None for non-HTMX requests.
  • history_restore_request: str – Mirrors the HX-History-Restore-Request header: True if the request is for history restoration after a miss in the local history cache.
  • prompt: str | None – Mirrors HX-Prompt: The user response to hx-prompt if it was used, or None.
  • target: str | None – Mirrors HX-Target: The id of the target element if it exists, or None.
  • trigger: str | None – Mirrors HX-Trigger: The id of the trigger element if it exists, or None.
  • trigger_name: str | None – Mirrors HX-Trigger-Name: The name of the trigger element if it exists, or None.
  • triggering_event: Any | None – Mirrors Triggering-Event, which is set by the event-header extension: The deserialized JSON representation of the event that triggered the request if it exists, or None.

HtmxRequest

For Starlette-based frameworks, use this instead of the standard starlette.requests.Request so that code editors understand that request.scope["htmx"] contains an HtmxDetails instance:

from asgi_htmx import HtmxRequest as Request

async def home(request: Request):
    reveal_type(request.scope["htmx"])  # Revealed type is 'HtmxDetails'

License

MIT

GitHub

View Github