Skip to main content
jax
home install tokens components htmx guide case study grounding changelog roadmap
Getting Started
Home Installation Design Tokens HTMX Guide case study grounding changelog roadmap
Components
Button Card Media Card Badge Form Alert Dialog Table Navbar Tabs Accordion Toast Dropdown Spinner Skeleton Toggle Tooltip File Input Tag Segmented Drawer Stat Card Gauge Sparkline Radio Group Data Table Feed & Hero Prose
Layout
Container Grid Stack

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