a-organvm/htmx-interaction-patterns

htmx Interaction Patterns

Build dynamic interfaces with HTML-over-the-wire — server renders HTML fragments, htmx swaps them in.

Core Concepts

htmx extends HTML with attributes that make AJAX requests and swap content — no JavaScript required.

<!-- Click button → GET /items → replace #item-list content -->
<button hx-get="/items" hx-target="#item-list" hx-swap="innerHTML">
  Load Items
</button>
<div id="item-list"></div>

Key Attributes

| Attribute | Purpose | Example | |-----------|---------|---------| | hx-get | GET request | hx-get="/api/items" | | hx-post | POST request | hx-post="/api/items" | | hx-put | PUT request | hx-put="/api/items/1" | | hx-delete | DELETE request | hx-delete="/api/items/1" | | hx-target | Where to put response | hx-target="#results" | | hx-swap | How to insert | hx-swap="outerHTML" | | hx-trigger | When to fire | hx-trigger="click" | | hx-indicator | Loading indicator | hx-indicator="#spinner" |

Swap Strategies

| Strategy | Behavior | |----------|----------| | innerHTML | Replace children (default) | | outerHTML | Replace entire target element | | afterbegin | Insert as first child | | beforeend | Insert as last child | | beforebegin | Insert before target | | afterend | Insert after target | | delete | Remove target | | none | No DOM update |

Common Patterns

Search with Debounce

<input type="search" name="q"
  hx-get="/search"
  hx-trigger="input changed delay:300ms"
  hx-target="#results"
  hx-indicator="#search-spinner"
  placeholder="Search skills...">
<span id="search-spinner" class="htmx-indicator">Searching...</span>
<div id="results"></div>

Server returns an HTML fragment:

@app.get("/search")
async def search(q: str = ""):
    results = search_skills(q)
    return HTMLResponse(render_results(results))

Inline Editing

<!-- View mode -->
<div id="skill-42" hx-get="/skills/42/edit" hx-trigger="dblclick" hx-swap="outerHTML">
  <h3>testing-patterns</h3>
  <p>Write effective tests across the stack...</p>
</div>

<!-- Edit mode (returned by server) -->
<form id="skill-42" hx-put="/skills/42" hx-swap="outerHTML">
  <input name="name" value="testing-patterns">
  <textarea name="description">Write effective tests...</textarea>
  <button type="submit">Save</button>
  <button hx-get="/skills/42" hx-swap="outerHTML">Cancel</button>
</form>

Infinite Scroll

<div id="item-list">
  <!-- Items rendered here -->
  <div hx-get="/items?page=2"
       hx-trigger="revealed"
       hx-swap="outerHTML">
    Loading more...
  </div>
</div>

Server returns items + next trigger:

<div class="item">Item 11</div>
<div class="item">Item 12</div>
<!-- Next page trigger -->
<div hx-get="/items?page=3" hx-trigger="revealed" hx-swap="outerHTML">
  Loading more...
</div>

Lazy Loading

<div hx-get="/dashboard/metrics" hx-trigger="load" hx-swap="innerHTML">
  <div class="skeleton-loader"></div>
</div>

Active Search with URL State

<input type="search" name="q"
  hx-get="/search"
  hx-trigger="input changed delay:300ms"
  hx-target="#results"
  hx-push-url="true">

Confirmation Dialogs

<button hx-delete="/items/42"
        hx-confirm="Delete this item?"
        hx-target="#item-42"
        hx-swap="outerHTML swap:500ms">
  Delete
</button>

Server-Sent Events

<div hx-ext="sse" sse-connect="/events" sse-swap="message">
  Waiting for updates...
</div>

from sse_starlette.sse import EventSourceResponse

@app.get("/events")
async def events():
    async def generate():
        while True:
            data = await get_update()
            yield {"data": render_update(data)}
    return EventSourceResponse(generate())

Server-Side Patterns

Partial vs Full Responses

@app.get("/items")
async def list_items(request: Request):
    items = await get_items()
    if "HX-Request" in request.headers:
        # htmx request: return fragment
        return HTMLResponse(render_items_fragment(items))
    else:
        # Normal request: return full page
        return HTMLResponse(render_full_page(items))

Response Headers

from starlette.responses import HTMLResponse

@app.post("/items")
async def create_item(request: Request):
    item = await save_item(request)
    response = HTMLResponse(render_item(item))
    response.headers["HX-Trigger"] = "itemCreated"  # Client-side event
    response.headers["HX-Retarget"] = "#item-list"
    response.headers["HX-Reswap"] = "afterbegin"
    return response

OOB (Out-of-Band) Swaps

Update multiple elements from one response:

<!-- Primary swap -->
<div id="item-42">Updated item content</div>
<!-- OOB: also update the counter -->
<span id="item-count" hx-swap-oob="true">43 items</span>

CSS Integration

/* Loading indicator */
.htmx-indicator { opacity: 0; transition: opacity 200ms; }
.htmx-request .htmx-indicator { opacity: 1; }

/* Settling animation */
.htmx-settling { opacity: 0; }
.htmx-settled { opacity: 1; transition: opacity 300ms; }

/* Added items */
.htmx-added { opacity: 0; }
.htmx-settled.htmx-added { opacity: 1; transition: opacity 300ms; }

Anti-Patterns

• Returning JSON from htmx endpoints — Always return rendered HTML fragments
• Large page replacements — Return small, targeted fragments
• No loading indicators — Always show feedback during requests
• Ignoring non-htmx requests — Support full-page loads for bookmarkability
• Client-side state management — Keep state on the server; let HTML be the state