Boost Server-Rendered Navigation with htmx hx-boost

The problem: full-page reloads on a server-rendered site

You maintain a server-rendered application. Every link click tears down the page and reloads it: a white flash, lost scroll position, and a round-trip for HTML you already have. Rewriting the app as a single-page application means JSON endpoints, client routing, and duplicating view logic. You want faster navigation without abandoning the server-side HTML that already works.

What hx-boost actually does

htmx’s hx-boost attribute lets ordinary links and forms keep working exactly as they do today while opting them into AJAX navigation. Place hx-boost="true" on a container, and every descendant anchor and form submission becomes an AJAX request. The server continues returning normal HTML pages; htmx swaps the current document body with the response and pushes a history entry, so the back button works like standard navigation. Individual elements can opt out with hx-boost="false". Because it works with HTML responses, it is a poor fit for JSON APIs without extra client handling.

Worked example: boost a navigation bar

Add the attribute to your layout template. No build step is required beyond loading htmx.

<body hx-boost="true">
  <nav>
    <a href="/invoices">Invoices</a>
    <a href="/invoices/new">New Invoice</a>
    <a href="/logout" hx-boost="false">Log out</a>
  </nav>
  <main>
    <!-- page content -->
  </main>
</body>

Where to run: edit your server-side template file directly. Required permissions: write access to the template; no server restart is usually needed. Forms work the same way—a boosted POST to /invoices sends the same fields via AJAX, and the server can return the same HTML it would for a normal submission.

Expected checks: open DevTools to the Network tab, click Invoices, and confirm the address bar changes to /invoices without a full reload or white flash. The request header HX-Request: true should be present, and the response body should be HTML. Click the Log out link: it should perform a standard full-page navigation while neighboring links stay boosted.

Risk: if /invoices returns a complete HTML document with its own <html>, <head>, or <body> tags, htmx may insert that markup inside the current <body>, producing invalid nested tags. Keep boosted endpoints returning body fragments, or configure your server to strip layout wrappers for AJAX requests.

Diagnose before you roll it out

• Open DevTools Network, submit a boosted form, and verify the request header HX-Request is present and the response body is HTML.
• Click back after several boosted navigations and confirm the prior page content and scroll state are restored by the browser.
• Mark one link with hx-boost="false" and confirm it performs a standard full-page navigation while neighboring links stay boosted.
• Run curl -H "HX-Request: true" https://your-app.com/invoices in your terminal. No special permissions are required. Expect an HTML response. This checks the server header path only; it does not test the DOM swap or browser history.

Where it falls short

• JavaScript bound with DOMContentLoaded does not re-run after an htmx swap. Maps, charts, or rich-text editors initialized that way can break. Use the htmx:afterSwap event or event delegation instead.
• Full-page HTML responses with <html>, <head>, or <body> tags can cause unexpected markup when swapped into the current page.
• Boosted navigation depends on the browser history stack and behaves differently from single-page application routing libraries.
• Server redirects after boosted form submissions may replace the whole page instead of updating a fragment.

Start small and verify

Add hx-boost="true" to <body> for a low-risk slice of internal links. Verify with DevTools, opt out the links that need full reloads, and only then consider finer-grained attributes such as hx-get or hx-post. Because this is a declarative HTML attribute, removing it returns navigation to ordinary browser behavior immediately; there is no server state to roll back.