HTMX is a small (~14KB gzipped) JavaScript library that extends HTML with attributes for making AJAX requests, handling server-sent events, and performing WebSocket communication—all without writing JavaScript. Instead of building a client-side application that consumes JSON APIs and renders UI in the browser, HTMX returns HTML fragments from the server and swaps them into the existing page. This server-driven approach moves application logic back to the server while maintaining the interactive, single-page feel that users expect.
The core idea behind HTMX is that HTML itself should be the hypermedia format for application interactions. Traditional web applications use <a> and <form> elements for navigation and data submission, but these only support GET and POST requests and always replace the entire page. HTMX generalizes this model: any element can trigger any HTTP method, target any part of the page for replacement, and respond to any DOM event. This transforms HTML from a static document format into a dynamic application interface.
HTMX is particularly well-suited for applications with server-rendered templates (Go templates, Jinja2, ERB, Blade) where the backend already knows how to produce HTML. Rather than duplicating rendering logic in a JavaScript framework, HTMX lets the server render partial HTML responses that update specific page regions. This eliminates the JSON serialization/deserialization layer, reduces client-side complexity, and keeps the application’s source of truth on the server where it has direct access to the database and business logic.
These attributes attach HTTP requests to any HTML element. When the element’s trigger event fires (click by default for buttons, submit for forms), HTMX sends the specified request and processes the HTML response. Unlike traditional forms that navigate to a new page, these requests happen in the background and the response HTML is swapped into the current page. The attribute value is the URL endpoint, and request parameters are automatically collected from form inputs or hx-vals attributes.
The hx-target attribute specifies which DOM element receives the HTML response. By default, the response replaces the element that triggered the request, but hx-target can point to any CSS selector: hx-target="#results" replaces the element with id “results”, hx-target="closest tr" targets the nearest table row ancestor, and hx-target="find .content" targets a descendant. This decoupling of trigger and target is what enables partial page updates without full-page navigation.
The hx-swap attribute controls how the response HTML is inserted relative to the target element. Options include innerHTML (replace children, the default), outerHTML (replace the target itself), beforebegin / afterbegin / beforeend / afterend (insert adjacent), delete (remove the target), and none (process headers but don’t modify DOM). Swap modifiers like swap:500ms add transition timing, and scroll:top scrolls the target into view after swapping.
The hx-trigger attribute controls which DOM event initiates the request. Beyond the defaults (click for most elements, submit for forms, change for inputs), you can specify any DOM event: hx-trigger="mouseenter", hx-trigger="keyup changed delay:500ms" (debounced input), hx-trigger="revealed" (element scrolls into viewport for infinite scroll), hx-trigger="every 2s" (polling), or hx-trigger="load" (fire immediately on page load). Multiple triggers are separated by commas.
HTMX expects the server to return HTML fragments, not JSON. A search endpoint returns rendered search result rows, not a JSON array. A form submission returns the updated form with validation errors rendered, not an error object. This means server templates render partial views (just the component that changed) rather than full pages. The server controls what the UI looks like after every interaction, making it the single source of truth for both data and presentation.
When a user interacts with an HTMX-enhanced element, the library intercepts the event, sends an HTTP request with appropriate headers (including HX-Request: true so the server can distinguish HTMX requests from full page loads), receives the HTML response, and swaps it into the target element. The server returns only the HTML fragment needed for the update, not a full page.
<!-- Button that loads search results into a div -->
<input type="search"
name="q"
hx-get="/api/search"
hx-trigger="keyup changed delay:300ms"
hx-target="#search-results"
hx-indicator="#spinner"
placeholder="Search topics...">
<span id="spinner" class="htmx-indicator">Loading...</span>
<div id="search-results"></div>The server handler checks for the HX-Request header to determine whether to return a full page or just the HTML fragment. For HTMX requests, it renders only the partial template containing the updated content.
// Go handler using html/template
func searchHandler(w http.ResponseWriter, r *http.Request) {
query := r.URL.Query().Get("q")
results := searchTopics(query)
// Check if this is an HTMX request
if r.Header.Get("HX-Request") == "true" {
// Return only the results fragment
tmpl := template.Must(template.ParseFiles("templates/partials/search-results.html"))
tmpl.Execute(w, results)
return
}
// Full page render for non-HTMX requests
tmpl := template.Must(template.ParseFiles(
"templates/layout.html",
"templates/search.html",
"templates/partials/search-results.html",
))
tmpl.ExecuteTemplate(w, "layout", map[string]interface{}{
"Query": query,
"Results": results,
})
}The partial template renders just the content fragment that HTMX will swap into the page. It produces standalone HTML without the page layout wrapper.
<!-- templates/partials/search-results.html -->
{{if .}}
{{range .}}
<div class="result-card">
<h3>{{.Title}}</h3>
<p>{{.Description}}</p>
<span class="tag">{{.Category}}</span>
</div>
{{end}}
{{else}}
<p class="no-results">No topics found.</p>
{{end}}HTMX supports polling via the every trigger modifier. The server returns updated HTML at each interval, and HTMX swaps it in place. For smarter polling, the server can return a 286 status code to tell HTMX to stop polling (useful when a background job completes).
<!-- Poll for job status every 2 seconds -->
<div hx-get="/jobs/{{.JobID}}/status"
hx-trigger="every 2s"
hx-swap="outerHTML">
<div class="progress-bar">
<div class="fill" style="width: {{.Progress}}%"></div>
</div>
<p>Processing... {{.Progress}}%</p>
</div>An internal dashboard project uses HTMX extensively with Go’s html/template package to build interactive admin interfaces without a JavaScript build step. Navigation between dashboard views uses hx-get with hx-push-url="true" to update the browser URL and history, creating SPA-like navigation while keeping all rendering server-side. Filter controls use hx-get with hx-trigger="change" to reload data tables when dropdown selections change.
Internal monitoring dashboards use HTMX polling (hx-trigger="every 5s") to refresh metric displays. Each metric card is a separate HTMX target, so only the changed numbers re-render rather than the entire dashboard. The server compares current values to previous ones and includes CSS classes for visual indicators (green for improvements, red for degradations) directly in the HTML response.
Configuration pages use HTMX for inline editing: clicking an “Edit” button sends hx-get="/settings/edit" which returns a form fragment that replaces the static display. Submitting the form via hx-put="/settings" returns the updated static display, completing the edit cycle without any page navigation. Validation errors return the form with error messages pre-rendered, avoiding client-side validation logic duplication.
This pattern loads more content as the user scrolls down, using the revealed trigger to detect when a sentinel element enters the viewport.
<!-- Initial page with first batch of items -->
<div id="item-list">
{{range .Items}}
<div class="item-card">
<h3>{{.Title}}</h3>
<p>{{.Summary}}</p>
</div>
{{end}}
{{if .HasMore}}
<div hx-get="/items?page={{.NextPage}}"
hx-trigger="revealed"
hx-swap="outerHTML"
hx-indicator="#load-more-spinner">
<span id="load-more-spinner" class="htmx-indicator">
Loading more...
</span>
</div>
{{end}}
</div>The server handler for subsequent pages returns more items plus a new sentinel element (if more pages exist), creating a chain of lazy-loaded content.
// Go handler for paginated items
func itemsHandler(w http.ResponseWriter, r *http.Request) {
page, _ := strconv.Atoi(r.URL.Query().Get("page"))
if page == 0 {
page = 1
}
items, total := getItems(page, 20)
hasMore := page*20 < total
data := struct {
Items []Item
HasMore bool
NextPage int
}{items, hasMore, page + 1}
tmpl := template.Must(template.ParseFiles("templates/partials/item-batch.html"))
tmpl.Execute(w, data)
}This pattern uses HTMX’s hx-confirm for simple confirmations and out-of-band swaps to update multiple page regions from a single response.
<!-- Delete button with confirmation -->
<button hx-delete="/items/{{.ID}}"
hx-confirm="Delete '{{.Title}}'? This cannot be undone."
hx-target="closest .item-row"
hx-swap="outerHTML swap:300ms">
Delete
</button>
<!-- The item count badge updates via out-of-band swap -->
<span id="item-count" class="badge">{{.TotalCount}} items</span>The server response includes both the primary swap content and an out-of-band update for the item count:
// Go handler for delete
func deleteItemHandler(w http.ResponseWriter, r *http.Request) {
id := chi.URLParam(r, "id")
deleteItem(id)
remaining := countItems()
// Primary response: empty string removes the row via outerHTML swap
// OOB swap updates the count badge independently
fmt.Fprintf(w, `<span id="item-count" hx-swap-oob="true" class="badge">%d items</span>`, remaining)
}This pattern combines debounced input, loading indicators, and URL synchronization for a search-as-you-type experience.
<!-- Search form with HTMX attributes -->
<form hx-get="/search"
hx-trigger="submit, keyup changed delay:400ms from:#search-input"
hx-target="#results-container"
hx-push-url="true"
hx-indicator="#search-spinner">
<div class="search-bar">
<input type="search"
id="search-input"
name="q"
value="{{.Query}}"
placeholder="Search documentation..."
autocomplete="off">
<svg id="search-spinner" class="htmx-indicator spinner">...</svg>
</div>
</form>
<div id="results-container">
{{template "search-results" .}}
</div>The CSS for HTMX indicators uses the .htmx-indicator and .htmx-request classes that HTMX toggles automatically:
/* HTMX loading indicator styles */
.htmx-indicator {
display: none;
}
.htmx-request .htmx-indicator,
.htmx-request.htmx-indicator {
display: inline-block;
}
/* Fade transition for swapped content */
.htmx-swapping {
opacity: 0;
transition: opacity 200ms ease-out;
}
.htmx-settling {
opacity: 1;
transition: opacity 200ms ease-in;
}<html>, <head>, <body>) for HTMX requests. This nests an entire page inside the target element. Always check the HX-Request header and return only the relevant HTML fragment for partial updates.hx-target, HTMX replaces the triggering element itself. For buttons, this means the button disappears and is replaced by the response content. Always set hx-target to the container that should receive the update.hx-headers on the body element or use the htmx:configRequest event to add it globally. Forgetting this causes 403 errors on all mutating requests.hx-push-url="true" adds entries to the browser history, but the back button loads the full URL without HTMX. The server must handle these requests by returning full pages (when HX-Request header is absent) to avoid broken back-button navigation.htmx:beforeSwap event to clean up before content replacement.hx-trigger="every 1s" on multiple elements creates a sustained load on the server. Use longer intervals, the 286 stop-polling response, or server-sent events (hx-sse) for truly real-time data instead of aggressive polling.