HTMX & Go: Server-Side Rendering for Dynamic UIs

beginner 9 min read updated 9 Aug 2026

On this page 5

HTMX’s Role: Server-Side Rendered UIs
Go HTMX Project: Initial Setup Steps
HTMX with Go: Building Dynamic Components
HTMX Go Errors: What Breaks and Why
HTMX Go Application: A Hands-On Exercise

HTMX’s Role: Server-Side Rendered UIs

Web applications require dynamic user interfaces, but the core HyperText Markup Language is inherently static. Historically, making a web page interactive meant either a full page reload for every user action or writing extensive client-side JavaScript to manipulate the Document Object Model (DOM) directly. The latter approach evolved into Single Page Application (SPA) frameworks, where a substantial JavaScript application runs in the browser, handling routing, data fetching, and UI rendering.

HTMX offers an alternative by extending HTML with attributes that enable AJAX requests directly from any element. Instead of JavaScript, these attributes tell the browser which HTTP request to make, which part of the DOM to update, and how to swap the new content. This allows the server to remain the primary renderer for UI components, even for partial page updates.

Consider a simple interaction like loading more items into a list. With HTMX, the HTML might look like this:

<button hx-get="/items?page=2" hx-swap="outerHTML">Load More Items</button>

When a user clicks this button, HTMX intercepts the click event. It then performs a GET request to /items?page=2. The server responds with an HTML fragment containing the new items, perhaps wrapped in a new button for the next page. HTMX takes this server-provided HTML and replaces the original button element with it, as specified by hx-swap="outerHTML". The browser’s DOM updates without a full page refresh, and without any custom JavaScript for this interaction.

This approach simplifies the development of dynamic UIs by shifting the complexity back to the server. Your Go backend, already responsible for generating full HTML pages, now also generates smaller HTML fragments. There is no need for a client-side JavaScript framework to manage application state, client-side routing, or data fetching via JSON APIs for these dynamic updates. The server dictates the UI structure and content directly in HTML.

The primary advantage over traditional SPA frameworks is a significantly reduced client-side codebase. Developers spend less time writing client-side JavaScript for UI logic and more time building robust backend services that render HTML. This often leads to a more unified codebase where Go’s templating engine handles all UI rendering, whether for initial page loads or subsequent dynamic updates. The tradeoff is that each dynamic interaction requires a round trip to the server, potentially increasing server load and network traffic compared to a fully client-side rendered SPA that fetches only data.

Go HTMX Project: Initial Setup Steps

Begin by establishing a new Go module for the project. Create a directory named go-htmx-app, then navigate into it and initialize the module. This sets up the project structure and prepares it for Go dependencies.

mkdir go-htmx-app
cd go-htmx-app
go mod init go-htmx-app

HTMX operates as a client-side JavaScript library. To use it, you need the htmx.min.js file. Create a static directory within your project, then place the downloaded HTMX script inside it. Fetch the latest stable version directly using curl:

mkdir static
curl -o static/htmx.min.js https://unpkg.com/htmx.org@1.9.12/dist/htmx.min.js

Next, create a basic index.html file inside the static directory. This file will serve as the entry point for the web application and include the HTMX script, making its functionality available in the browser.

<!-- static/index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>HTMX & Go App</title>
    <script src="/htmx.min.js"></script>
</head>
<body>
    <h1>Welcome to HTMX & Go</h1>
    <button hx-get="/hello" hx-swap="outerHTML">Load Greeting</button>
</body>
</html>

This index.html includes a button configured with hx-get="/hello" and hx-swap="outerHTML". When clicked, HTMX will send an HTTP GET request to the /hello endpoint on the server and replace the button’s HTML with the server’s response. The <script src="/htmx.min.js"></script> line ensures the HTMX library loads correctly.

Now, set up the Go server to serve these static files and handle the /hello request. Create a main.go file in the project’s root directory:

// main.go
package main

import (
	"fmt"
	"log"
	"net/http"
)

func main() {
	// Serve static files from the "static" directory
	fs := http.FileServer(http.Dir("./static"))
	http.Handle("/", fs)

	// Handler for the /hello endpoint
	http.HandleFunc("/hello", func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprint(w, "<h2>Hello from Go!</h2>")
	})

	log.Println("Server starting on :8080...")
	err := http.ListenAndServe(":8080", nil)
	if err != nil {
		log.Fatal(err)
	}
}

This main.go configures http.FileServer to make all content within the static directory accessible via the root URL path. For instance, static/index.html becomes /index.html. It also defines a handler for /hello that responds with a simple HTML greeting. This completes the basic server configuration.

Run the Go server from your project root:

go run main.go

Open your browser to http://localhost:8080. You should see the “Welcome to HTMX & Go” page. Clicking the “Load Greeting” button will trigger an HTMX request to the Go server, which then responds with “Hello from Go!”, replacing the button. This confirms the initial setup is functional.

HTMX with Go: Building Dynamic Components

Building dynamic UI components traditionally involves JavaScript to fetch data and manipulate the DOM. HTMX enables this interaction directly from HTML by adding special attributes that trigger HTTP requests and update parts of the page with server responses.

Consider a scenario where a button loads additional items into a list. The initial HTML might contain an empty container and a button:

<div id="items-container">
    <!-- Items will be loaded here -->
</div>
<button hx-get="/load-items" hx-target="#items-container" hx-swap="beforeend">
    Load More Items
</button>

The hx-get="/load-items" attribute instructs HTMX to make an HTTP GET request to /load-items when the button is clicked. hx-target="#items-container" specifies that the server’s response should be placed inside the element with id="items-container". hx-swap="beforeend" dictates that the response HTML should be appended as the last child of the target element, rather than replacing its entire content.

The Go backend defines a handler for /load-items. This handler’s primary responsibility is to render a small HTML template fragment containing the new items.

package main

import (
	"html/template"
	"log"
	"net/http"
)

// handleLoadItems processes the HTMX request for more items.
func handleLoadItems(w http.ResponseWriter, r *http.Request) {
	// In a real application, fetch items from a database or service.
	// For this example, we use hardcoded data.
	newItems := []struct{ ID int; Name string }{
		{ID: 4, Name: "New Item A"},
		{ID: 5, Name: "New Item B"},
		{ID: 6, Name: "New Item C"},
	}

	tmpl := template.Must(template.New("item-list").Parse(`
		{{range .}}
			<p>Item {{.ID}}: {{.Name}}</p>
		{{end}}
	`))

	w.Header().Set("Content-Type", "text/html")
	if err := tmpl.Execute(w, newItems); err != nil {
		http.Error(w, "Failed to render items", http.StatusInternalServerError)
		return
	}
}

func main() {
	http.HandleFunc("/load-items", handleLoadItems)
	// Assume an index.html or similar serves the initial page.
	// http.Handle("/", http.FileServer(http.Dir("./static"))) 
	log.Fatal(http.ListenAndServe(":8080", nil))
}

When a user clicks the ‘Load More Items’ button, HTMX sends a GET request to /load-items. The Go handler processes this request, generates the HTML fragment for newItems, and sends it back. HTMX then takes this fragment and inserts it into the items-container div, effectively updating the UI without a full page reload or explicit JavaScript.

This method simplifies client-side development by removing JavaScript for common dynamic interactions. The tradeoff is that the server now handles more rendering logic, sending HTML fragments instead of raw data. This can increase server load or network traffic if fragments are large, but often provides a faster perceived user experience due to less client-side parsing and rendering.

HTMX Go Errors: What Breaks and Why

HTMX relies on specific server responses to update the DOM correctly. Misconfigurations in the Go backend or HTML attributes often lead to unresponsive UIs or unexpected content rendering. Understanding these common pitfalls helps in debugging and building reliable applications.

A frequent error is sending an incorrect Content-Type header from the Go server. HTMX expects HTML fragments, meaning the server must respond with text/html. If the header is missing or set to application/json, the browser might attempt to download the response, or HTMX will fail to interpret the content as valid HTML for DOM manipulation.

The Go handler must explicitly set this header:

func handleItems(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "text/html")
    // Render an HTML template fragment
    tmpl.ExecuteTemplate(w, "item-list-fragment.html", data)
}

Another common mistake involves returning a full HTML page instead of a partial fragment. HTMX makes AJAX requests to replace specific parts of the DOM. If your Go handler renders the entire layout.html including <head> and <body> tags, HTMX will attempt to insert this full document into the target element, leading to malformed nested HTML structures or script re-execution issues.

Consider a Go template for a full page:

<!-- layout.html -->
<!DOCTYPE html>
<html lang="en">
<head>
    <title>My App</title>
</head>
<body>
    <div id="content">
        {{ template "item-list-fragment.html" . }}
    </div>
</body>
</html>

The server should only render the fragment when an HTMX request is detected, typically via the HX-Request header. A handler rendering the full layout.html for an HTMX request is incorrect. Instead, render only the specific partial, like item-list-fragment.html:

func handleItems(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "text/html")
    if r.Header.Get("HX-Request") == "true" {
        tmpl.ExecuteTemplate(w, "item-list-fragment.html", data) // Render only the fragment
    } else {
        tmpl.ExecuteTemplate(w, "layout.html", data) // Render full page for initial load
    }
}

Finally, misconfiguring hx-target or hx-swap attributes prevents the UI from updating as expected. hx-target specifies the DOM element to update, while hx-swap dictates how the response HTML replaces the target’s content. An incorrect hx-target means HTMX cannot find the element, leading to no visible change. An hx-swap value like innerHTML (the default) might replace only the inside of a target when you intended to replace the target element itself, requiring outerHTML.

Ensure your HTML attributes correctly point to existing elements and define the intended swap behavior:

<button hx-post="/items" hx-target="#item-list-container" hx-swap="outerHTML">Load More Items</button>

Here, the button’s click posts to /items, expecting the response to replace the entire #item-list-container element. If #item-list-container does not exist or hx-swap was innerHTML, the update would fail or behave differently.

HTMX Go Application: A Hands-On Exercise

This exercise constructs a minimal web application allowing users to add text items to a list dynamically. The Go backend manages an in-memory item store and renders HTML fragments in response to HTMX requests.

Begin by creating a new project directory and initializing a Go module:

mkdir htmx-go-items
cd htmx-go-items
go mod init htmx-go-items

Create an index.html file in the project root. This file contains a form for submitting new items and a div element that will display the current list. The HX-POST attribute on the form specifies the endpoint for submission, HX-TARGET directs the response to the items-list div, and HX-SWAP replaces the entire outer HTML of the target.

<!-- index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>HTMX Go Items</title>
    <script src="https://unpkg.com/htmx.org@1.9.10" defer></script>
</head>
<body>
    <h1>Item List</h1>

    <form hx-post="/items" hx-target="#items-list" hx-swap="outerHTML">
        <input type="text" name="item" placeholder="New item" required>
        <button type="submit">Add Item</button>
    </form>

    <div id="items-list">
        <!-- Initial items will be rendered here by the server -->
    </div>
</body>
</html>

The Go application, main.go, will serve this static index.html and handle the /items endpoint. A slice holds the items in memory, protected by a mutex for concurrent access. The renderItems function generates the complete HTML for the item list, wrapped in its items-list div, which is then sent back to the client.

// main.go
package main

import (
	"fmt"
	"html/template"
	"log"
	"net/http"
	"sync"
)

var (
	items []string
	mu    sync.Mutex // Protects access to 'items'
)

// init runs before main to add some initial items
func init() {
	items = []string{"First item", "Second item"}
}

func main() {
	http.Handle("/", http.FileServer(http.Dir("."))) // Serves index.html and HTMX script
	http.HandleFunc("/items", handleItems)

	fmt.Println("Server listening on :8080")
	log.Fatal(http.ListenAndServe(":8080", nil))
}

func handleItems(w http.ResponseWriter, r *http.Request) {
	mu.Lock()
	defer mu.Unlock()

	if r.Method == http.MethodPost {
		item := r.FormValue("item")
		if item != "" {
			items = append(items, item)
		}
	}

	renderItems(w)
}

func renderItems(w http.ResponseWriter) {
	tmpl, err := template.New("items").Parse(`
        <div id="items-list">
            <ul>
                {{range .}}
                    <li>{{.}}</li>
                {{end}}
            </ul>
        </div>
    `)
	if err != nil {
		http.Error(w, "Template parsing error", http.StatusInternalServerError)
		return
	}

	err = tmpl.Execute(w, items)
	if err != nil {
		http.Error(w, "Template execution error", http.StatusInternalServerError)
	}
}

Run the Go application from the project root:

go run main.go

Navigate your browser to http://localhost:8080. Type text into the input field and click “Add Item”. The new item appears in the list without a full page reload, demonstrating HTMX’s ability to swap server-rendered HTML fragments into the DOM.

Spotted an error? Tell us via the corrections process — verified reports get fixed and credited.