HTMX + Go: A Practical Pattern for Partial and Full-Page HTML Rendering

Alex Edwards has published a detailed walkthrough of how he integrates HTMX with Go web applications. The post focuses on the server-side patterns that make HTMX work smoothly with Go's html/template package, covering template organization, partial vs. full-page responses, redirects, and error handling.

Template structure

Edwards uses a three-tier template layout: a base template (base.tmpl) for the common HTML shell, page-specific templates in pages/, and reusable partials in partials/. All templates are explicitly named with {{define}} actions for consistency — no mixing of filenames and defined names. The base template includes HTMX via a defer script tag to avoid blocking DOM parsing.

Partial rendering with HTMX

A button with hx-get="/gopher" and hx-swap="outerHTML" triggers a GET request that returns a partial HTML snippet — in this case, an image of a gopher. Edwards notes that the server must detect HTMX requests (via the HX-Request header) and return only the partial template, not the full page layout. This keeps the client-side interaction fast and avoids re-rendering the entire DOM.

Redirect and error handling

Standard HTTP redirects don't work well with HTMX because the client expects HTML, not a redirect response. Edwards recommends using the HX-Redirect response header for HTMX-initiated requests, and falling back to normal redirects for regular browser requests. For errors, he suggests returning appropriate HTTP status codes (like 404 or 500) along with partial error templates, which HTMX can display inline without a full page reload.

Static asset embedding

All static assets (CSS, JS, images) are embedded into the Go binary using //go:embed. Edwards creates separate fs.FS instances for HTML templates and static files to keep concerns cleanly separated. A custom htmlRenderer type parses shared templates at startup and clones them per request, allowing efficient partial rendering without re-parsing templates on every call.

Configuration defaults

Edwards recommends setting htmx.config.historyEnabled = false to avoid unexpected history stack entries from partial updates, and htmx.config.scrollIntoViewOnBoost = false to prevent automatic scrolling on boosted links. These tweaks prevent common UX surprises when mixing HTMX with server-rendered pages.