Using HTMX hx-boost for AJAX Navigation with Graceful Degradation

Desired outcome

When a user clicks a link or submits a form, only a specific part of the page updates with the server’s HTML response. The URL in the address bar changes, and the browser’s back/forward buttons work without a full page reload. If HTMX is not available, the interaction falls back to a normal navigation.

Prerequisites

1. Include the HTMX library (version 1.9.0 or later) in the page’s <head> or just before the closing </body> tag:

<script src="https://unpkg.com/htmx.org@1.9.0"></script>

1. Ensure the server endpoint returns either an HTML fragment that matches the target selector or a full page that HTMX can swap into the target.
2. Have a container element in the markup where the new content will be placed, e.g., <div id="content"></div>.

Procedure

1. Mark up the link or form

Add the hx-boost="true" attribute to any <a> or <form> you want to behave as an AJAX navigation. Optionally specify where the response should go and how it should be inserted.

<!-- Example link -->
<a href="/about" hx-boost="true" hx-target="#content" hx-swap="innerHTML">About</a>

<!-- Example form -->
<form action="/search" method="get" hx-boost="true" hx-target="#content" hx-swap="innerHTML">
  <input type="text" name="q" placeholder="Search">
  <button type="submit">Go</button>
</form>

2. Verify the server response

Make sure the endpoint returns markup that can be placed inside #content. For a link to /about, a suitable response might be:

<section>
  <h1>About Us</h1>
  <p>We build things with HTMX.</p>
</section>

If the server returns a full HTML document, add hx-select="#main" (or another selector) to extract only the needed fragment.

3. Activate and observe

Load the page in a browser, open the developer tools, and click the boosted link or submit the form.

Expected checks

• Network tab shows a single XHR/fetch request to the target URL, not a full document reload.
• The #content element’s inner HTML updates with the server’s response.
• The address bar updates to the new URL (e.g., changes from /home to /about).
• Clicking the browser’s back button returns to the previous URL and restores the prior content without another request.
• Window.history.state contains a state object after navigation, confirming the HTML5 History API push.

Recovery options / graceful degradation

Handling request errors

HTMX fires the htmx:requestError event if the AJAX call fails. You can show a message or force a full navigation:

<a href="/about"
   hx-boost="true"
   hx-target="#content"
   hx-on::htmx::requestError="alert('Load failed'); location.href=this.href">
  About
</a>

Temporarily disabling HTMX

To test the fallback, run in the console:

htmx.config.disabled = true;

Now clicking the link or submitting the form performs a standard navigation, confirming that the enhancement degrades gracefully.

Limitations

• HTMX only swaps content based on the raw server response. If the endpoint returns a full page with <html> and <body> tags, the entire markup will be inserted into the target, causing duplicate tags unless you use hx-select to extract a fragment.
• Forms that rely on traditional side‑effects (e.g., file uploads) may need the server to detect AJAX requests and return appropriate responses; otherwise the boosted behavior can break expected upload handling.
• Boosted navigation does not automatically preserve scroll position or focus; you may need to handle those with additional events like htmx:afterSwap.

Verification checklist

1. Open the page with developer tools enabled.
2. Click a boosted link or submit a boosted form.
3. Confirm a single XHR/fetch request appears in the Network tab.
4. Check that #content updates and the URL changes.
5. Use the back/forward buttons and verify the content reverts correctly.
6. Run htmx.config.disabled = true in the console and repeat the action; ensure a full page load occurs.