HTMX Integration
Jax is built for HTMX. These patterns are extracted from production use in jax-bot.
Loading State
Buttons auto-switch between text and loading indicator during requests.
<button class="btn btn-primary"
hx-post="/save"
hx-disabled-elt="this">
<span class="btn-text">save</span>
<span class="btn-loading">[...]</span>
</button>
hx-disabled-elt="this" prevents double-submit.
Toast from Server
Trigger toasts from backend response headers.
# Python (FastAPI)
from fastapi.responses import HTMLResponse
@app.post("/save")
async def save():
# ... save logic ...
response = HTMLResponse("<span>saved</span>")
response.headers["HX-Trigger"] = json.dumps({
"jax:toast": {"message": "Saved!", "type": "ok"}
})
return response
The JS toast listener auto-picks up
jax:toast events from HTMX.
Partial Swaps
Return only the changed fragment, not the full page.
<!-- Toggle a badge inline -->
<div id="status-">
<button hx-post="/toggle/"
hx-target="#status-"
hx-swap="outerHTML">
<span class="badge badge-warn">PENDING</span>
</button>
</div>
Jinja2 Macros
All macros pass HTMX attributes via **kwargs.
{# Button with HTMX #}
{{ btn("save", variant="primary", hx_post="/save", hx_target="#result") }}
{# Toggle with HTMX #}
{{ toggle("auto_sync", checked=True, hx_post="/toggle/sync", hx_swap="outerHTML") }}
{# Form field #}
{{ form_field("email", label="Email", type="email", required=True) }}
{# Card with content #}
{% call card(title="Settings") %}
{{ form_field("name", label="Name", value=user.name) }}
{{ btn("save", variant="primary", hx_post="/settings") }}
{% endcall %}
Error Handling
| Status | Meaning | Response |
|---|---|---|
| 200 | Success | Updated partial HTML |
| 422 | Validation error | Error message partial |
| 500 | Server error | Triggers htmx:responseError |