HTMX Integration

Server-rendered HTMX patterns with loading indicators, error handling, and out-of-band swaps.

Overview

The htmx package provides first-class HTMX integration for server-rendered Go apps. HTMX follows HATEOAS — HTML is the source of truth, JavaScript enhances it rather than replacing it.

Loading Indicators

@htmx.LoadingIndicator(feedback.Spinner(feedback.SpinnerProps{Size: feedback.SpinnerMD, Color: "text-blue-600"}))
@htmx.InlineLoadingOverlay("form-loading", feedback.Spinner(feedback.SpinnerProps{Size: feedback.SpinnerSM, Color: "text-white"}))

Pair InlineLoadingOverlay with HTMX's hx-indicator attribute:

<button hx-post="/api/save" hx-indicator="#form-loading">Save</button>
<div id="form-loading" class="htmx-indicator">
  <!-- InlineLoadingOverlay renders here -->
</div>

Error Handling

@htmx.GlobalErrorHandling(htmx.DefaultErrorHandlingConfig())

When the server returns structured JSON with a family field, the toast type is automatically mapped (e.g., rejection → warning, transient → info).

Configure via ErrorHandlingConfig:

htmx.ErrorHandlingConfig{
    MaxErrorHistory: 10,
    MaxRetries:      3,
    RetryDelayMS:    1000,
}

CSRF Protection

@htmx.CSRFToken("your-csrf-token-value")

Renders a hidden <input> with the token. Use forms.FormProps.CSRFToken for form-based submissions.

Out-of-Band Swaps

@htmx.SwapOOB(htmx.SwapOOBProps{
    SwapStyle: htmx.SwapOuterHTML,
    Selector:  "#user-count",
})

View Transitions

@htmx.ViewTransitions(htmx.ViewTransitionsProps{Global: true})

Enables native View Transitions for HTMX swaps. Graceful degradation — browsers without View Transitions do instant swaps.

Per-Element Retry

<button hx-post="/api/save" data-tc-retry="0">Save</button>

The retry counter is set on the triggering element (event.detail.elt), not the swap target.