cofin/htmx

HTMX Skill

<workflow>

Quick Reference

Core Attributes

<example>

<!-- Basic request types -->
<button hx-get="/items">Load Items</button>
<button hx-post="/items" hx-vals='{"name": "New Item"}'>Create</button>
<button hx-put="/items/1">Update</button>
<button hx-delete="/items/1">Delete</button>

<!-- Specify target -->
<button hx-get="/items" hx-target="#item-list">Load</button>

<!-- Swap strategies -->
<div hx-get="/items" hx-swap="innerHTML">Replace content</div>
<div hx-get="/items" hx-swap="outerHTML">Replace element</div>
<div hx-get="/items" hx-swap="beforeend">Append</div>
<div hx-get="/items" hx-swap="afterbegin">Prepend</div>
<div hx-get="/items" hx-swap="delete">Delete element</div>

<!-- Triggers -->
<input hx-get="/search" hx-trigger="keyup changed delay:500ms">
<div hx-get="/updates" hx-trigger="every 5s">Polling</div>
<button hx-get="/modal" hx-trigger="click once">Open once</button>

</example>

OOB (Out of Band) Swaps

<example>

<!-- Server response with multiple updates -->
<div id="main-content">
  Main content here
</div>
<div id="notification" hx-swap-oob="true">
  New notification!
</div>
<div id="counter" hx-swap-oob="innerHTML">42</div>

</example>

Forms

<example>

<form hx-post="/users" hx-target="#result" hx-swap="outerHTML">
  <input name="name" required>
  <input name="email" type="email" required>
  <button type="submit">
    <span class="htmx-indicator">Saving...</span>
    <span>Save</span>
  </button>
</form>

<!-- With validation -->
<form hx-post="/users" hx-target="#result">
  <input name="email" hx-get="/validate/email" hx-trigger="blur">
  <span id="email-error"></span>
</form>

</example>

Indicators

<example>

<button hx-get="/slow" hx-indicator="#spinner">
  Load Data
  <img id="spinner" class="htmx-indicator" src="/spinner.svg">
</button>

<style>
  .htmx-indicator { display: none; }
  .htmx-request .htmx-indicator { display: inline; }
  .htmx-request.htmx-indicator { display: inline; }
</style>

</example>

Boosted Links

<example>

<!-- Boost all links in a section -->
<div hx-boost="true">
  <a href="/page1">Page 1</a>
  <a href="/page2">Page 2</a>
</div>

<!-- Push URL to history -->
<a hx-get="/page" hx-push-url="true">Navigate</a>

</example>

Events

<example>

<!-- Trigger on custom event -->
<div hx-get="/data" hx-trigger="myEvent from:body">
  Waiting for event...
</div>

<script>
  document.body.dispatchEvent(new Event('myEvent'));
</script>

<!-- Listen to htmx events -->
<script>
  document.body.addEventListener('htmx:afterSwap', (e) => {
    console.log('Swapped:', e.detail.target);
  });
</script>

</example>

Extensions

<example>

<!-- JSON encoding extension -->
<script src="https://unpkg.com/htmx.org/dist/ext/json-enc.js"></script>

<form hx-post="/api/users" hx-ext="json-enc">
  <input name="email" type="email">
  <button>Submit as JSON</button>
</form>

<!-- SSE extension -->
<div hx-ext="sse" sse-connect="/events" sse-swap="message">
  Live updates here
</div>

<!-- WebSocket extension -->
<div hx-ext="ws" ws-connect="/chat">
  <form ws-send>
    <input name="message">
  </form>
</div>

</example>

Headers & CSRF

<example>

<!-- Include CSRF token -->
<meta name="csrf-token" content="{{ csrf_token }}">

<script>
  document.body.addEventListener('htmx:configRequest', (e) => {
    e.detail.headers['X-CSRF-Token'] =
      document.querySelector('meta[name="csrf-token"]').content;
  });
</script>

</example>

Confirm & Prompt

<example>

<button hx-delete="/items/1" hx-confirm="Are you sure?">
  Delete
</button>

<button hx-post="/action" hx-prompt="Enter reason:">
  Action with reason
</button>

</example>

Server Response Headers

<example>

# Python example
response.headers["HX-Redirect"] = "/new-page"
response.headers["HX-Refresh"] = "true"
response.headers["HX-Trigger"] = "itemCreated"
response.headers["HX-Trigger-After-Swap"] = "formReset"
response.headers["HX-Reswap"] = "outerHTML"
response.headers["HX-Retarget"] = "#new-target"

</example>

Best Practices

• Return partial HTML, not full pages
• Use hx-swap-oob for updating multiple elements
• Add loading indicators for slow operations
• Use hx-boost for progressive enhancement
• Include CSRF tokens in headers
• Use semantic HTML for accessibility

</workflow>

References Index

• Litestar-Vite Integration — Backend integration with Litestar-Vite plugin.

Deployment

Hypermedia Strategy

HTMX applications are deployed bundled with their backend engine (e.g., Litestar). Deployment involves standard backend containerization or server hosting.

Static Assets

Ensure htmx.min.js and desired 2.x extensions are bundle-copied to the backend static directory.

---

CI/CD Actions

Example GitHub Actions workflow targeting Backend Tests ensuring partial content returns:

name: Backend CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Python
        uses: actions/setup-python@v5
      - run: pip install -r requirements.txt
      - run: pytest tests/ # Verify handlers return partial html correctly

Official References

• https://htmx.org/docs/
• https://htmx.org/reference/
• https://htmx.org/migration-guide-htmx-1/
• https://extensions.htmx.org/
• https://htmx.org/extensions/ws/
• https://github.com/bigskysoftware/htmx/releases

Shared Styleguide Baseline

• Use shared styleguides for generic language/framework rules to reduce duplication in this skill.
• General Principles
• HTMX
• Keep this skill focused on tool-specific workflows, edge cases, and integration details.

<guardrails> ## Guardrails

Add guardrails instructions here. </guardrails>

<validation> ## Validation

Add validation instructions here. </validation>