htmx

htmx Best Practices & Go/Templ Integration

Apply correct htmx patterns when building hypermedia-driven web applications, especially with Go and templ.

Core Principles

• Return HTML fragments, not JSON — htmx is designed for hypermedia; the server returns rendered HTML
• Use HTML attributes, not JavaScript — prefer hx-* attributes over htmx.ajax() or fetch() calls
• Server controls behavior — use response headers (HX-Retarget, HX-Reswap, HX-Redirect) for control flow
• Check HX-Request header — return fragments for htmx requests, full pages for normal requests
• Don't mix paradigms — avoid using fetch() alongside htmx in the same page; pick one approach

---

Reference Files

Read the relevant file for detailed patterns, code examples, and best practices:

templ-integration.md — Templ + htmx

• CRITICAL: Templ interpolation rules (dynamic attributes, { } vs quoted strings)
• Dynamic JSON in hx-vals — use json.Marshal, not fmt.Sprintf
• URL construction patterns (fmt.Sprintf, concatenation, templ.URL)
• Templ component patterns (spread attributes, conditional attributes, full page vs partial)
• JavaScript and hx-on events in templ (JSFuncCall, OnceHandle, event name syntax)
• Embedding Go data in script tags
• Alpine.js listening to htmx events from templ

go-handlers.md — Go Server Patterns

• Fragment vs full page response (isHTMXRequest helper)
• Separate routes for partials vs full pages
• Multi-target OOB responses (writing multiple components)
• htmx-aware redirects (HX-Redirect instead of HTTP 302)
• Event-driven list reloads with HX-Trigger header
• Delete with empty response
• Validation error re-rendering with error state

attributes-reference.md — Swap, Triggers & Headers

• Swap strategies table (innerHTML, outerHTML, delete, morph, etc.) and modifiers
• Trigger patterns (events, special triggers, modifiers, filters, multiple triggers)
• Self-terminating polling pattern
• Request headers (sent automatically) and response headers (server control)
• Out-of-Band (OOB) swap patterns and gotchas