HX-Location and HX-Redirect headers ignored during history restoration (back button navigation)

[kohkimakimoto]

HX-Location and HX-Redirect headers ignored during history restoration (back button navigation)

When htmx loads history from the server using the loadHistoryFromServer function, response headers like HX-Location and HX-Redirect are ignored.
This causes authentication applications to display blank pages when users press the back button after login.

Affected use case

This issue occurs when using hx-history="false", which forces htmx to load history from the server.
The following is an example flow that triggers this issue:

1. User displays login form
2. User successfully logs in and gets redirected to dashboard page that requires authentication
3. User presses browser back button
4. Browser returns to login form URL, htmx loads history from server (calls the loadHistoryFromServer function)
5. Server detects user is already authenticated, responds with HX-Location header to redirect to dashboard instead of returning login form HTML
6. htmx ignores the HX-Location header and swaps the empty HTTP response body
7. Result: the login form becomes blank instead of proper redirect

Suggested solution

Added header processing logic in the loadHistoryFromServer function that follows similar logic to the existing handleAjaxResponse function.

This ensures that HX-Location and HX-Redirect headers are properly handled during back button navigation, resolving the authentication flow issue that I described above.

[MichaelWest22]

I don't know if this is a real problem as Back button that does not hit the cache should always be treated by the backend like a full page server response. There is an issue that the HX-Request header is now returned during these requests which breaks many backend logics but this can be turned off with a config item now to return to the old behavior. There is also a HX-History-Restore-Request header that a backend can listen to so it knows to return a normal full page response and not a htmx partial response with htmx headers. You can use the htmx.config.historyRestoreAsHxRequest=false option and then use the existence of HX-Request header in your backend to know if its a htmx request or not or you can check if HX-Request header is present and HX-History-Restore-Request is not present to know.

In your login back button case you can detect if the request is a htmx request and either return the hx-location redirect or if not return a 3xx redirect response if they are already authenticated.

When re-writing history recently to use the swap() function I also tested implementing it just using a full htmx.ajax request instead which worked well but it caused history restore requests to start listening to all the HX response headers and added a lot of htmx request events and their is a risk this could cause an unexpected change in behavior for users.

[kohkimakimoto]

@MichaelWest22
Thank you for the detailed response. However, the proposed solutions don't fully address my use case.

The core issue is not the HX-Request header, but the fact that htmx uses XMLHttpRequest for history restoration. When returning a 3xx redirect response to XMLHttpRequest, the browser URL doesn't update. The XMLHttpRequest follows the redirect and fetches the target content, but the URL remains unchanged.

This leads to an inconsistent state:

• URL shows: /login (login page)
• Content shows: dashboard content (post-login page)

The same problem occurs when detecting HX-History-Restore-Request and returning a full page response - the URL still doesn't update.

What I need is the same behavior as direct URL access: when authenticated users visit the login page URL, they should be redirected to the dashboard with the URL properly updated (e.g., to /dashboard).

Since htmx uses XMLHttpRequest, handling HX-Location and HX-Redirect headers seems to be the only way to handle redirects during history restoration.

I understand this is a design decision about what server behavior htmx should support. It would also be reasonable to specify that history restoration does not support redirects and servers should always return full page content.

For my use case, I need redirect support during history restoration. Currently, I'm using this workaround with an event listener:

document.addEventListener('htmx:historyCacheMissLoad', function (e) {
  const xhr = e.detail.xhr;
  const redirectUrl = xhr.getResponseHeader('HX-Redirect') || xhr.getResponseHeader('HX-Location');
  
  if (redirectUrl) {
    window.location.href = redirectUrl;
    e.preventDefault();
  }
});

This works well, but built-in support would eliminate the need for such workarounds.

[MichaelWest22]

Yeah handling exceptions for your edge cases is often the best way to handle things. Also I recommend trying htmx.config.refreshOnHistoryMiss as this will turn all cache misses into proper browser navigations which makes things simpler.

Also extending the base htmx history support can ideally be done by writing htmx extensions as these can replace or upgrade the base behavior easily without adding code, complexity and unexpected behavior changes to the htmx core. Recent changes have expanded the history events and their ability to be overridden. So it should now be easy to for example create an extension that upgrades all history miss ajax requests to act more like full ajax requests and handle HX-Location and HX-Trigger etc. The extension may be as simple as just listening for htmx:historyCacheMissLoad like in your event listener.

a complete extension could be something like this

let api

htmx.defineExtension('history-full', {
  init: function(internalApi) {
    api = internalApi
  },

  onEvent: function(name, evt) {
    if (name === 'htmx:historyCacheMissLoad') {
      const xhr = evt.detail.xhr
      const swapSpec = evt.detail.swapSpec

      // Handle HX-Location (AJAX redirect)
      const locationHeader = xhr.getResponseHeader('HX-Location')
      if (locationHeader) {
        let redirectPath = locationHeader
        let redirectSwapSpec
        if (redirectPath.indexOf('{') === 0) {
          redirectSwapSpec = JSON.parse(redirectPath)
          redirectPath = redirectSwapSpec.path
          delete redirectSwapSpec.path
        }
        evt.detail.path = redirectPath
        htmx.ajax('get', redirectPath, redirectSwapSpec).then(function() {
          pushUrlIntoHistory(redirectPath)
        })
        swapSpec.swapStyle = 'none'
        return
      }

      // Handle HX-Redirect (full page redirect)
      const redirectUrl = xhr.getResponseHeader('HX-Redirect')
      if (redirectUrl) {
        window.location.href = redirectUrl
        swapSpec.swapStyle = 'none'
        return
      }

      // Handle refresh
      if (xhr.getResponseHeader('HX-Refresh') === 'true') {
        window.location.reload()
        swapSpec.swapStyle = 'none'
        return
      }

      // Handle HX-Reswap
      const reswapHeader = xhr.getResponseHeader('HX-Reswap')
      if (reswapHeader) {
        swapSpec.swapStyle = reswapHeader
      }

      // Handle HX-Retarget
      const retargetHeader = xhr.getResponseHeader('HX-Retarget')
      if (retargetHeader) {
        if (retargetHeader !== 'this') {
          const newTarget = htmx.find(retargetHeader)
          if (newTarget) {
            evt.detail.historyElt = newTarget
          }
        }
      }

      // Handle HX-Reselect
      const reselectHeader = xhr.getResponseHeader('HX-Reselect')
      if (reselectHeader) {
        const fragment = api.makeFragment(evt.detail.response)
        const selectedElement = fragment.querySelector(reselectHeader)
        if (selectedElement) {
          evt.detail.response = selectedElement.outerHTML
        }
      }

      // Handle triggers (let normal swap proceed)
      const triggerHeader = xhr.getResponseHeader('HX-Trigger')
      if (triggerHeader) {
        handleTriggerHeader(xhr, 'HX-Trigger', document.body)
      }

      const triggerAfterSwap = xhr.getResponseHeader('HX-Trigger-After-Swap')
      if (triggerAfterSwap) {
        setTimeout(() => handleTriggerHeader(xhr, 'HX-Trigger-After-Swap', document.body), swapSpec.swapDelay)
      }

      const triggerAfterSettle = xhr.getResponseHeader('HX-Trigger-After-Settle')
      if (triggerAfterSettle) {
        setTimeout(() => handleTriggerHeader(xhr, 'HX-Trigger-After-Settle', document.body), swapSpec.swapDelay + swapSpec.settleDelay)
      }
    }
  }

})

function handleTriggerHeader(xhr, header, elt) {
  const triggerBody = xhr.getResponseHeader(header)
  if (triggerBody.indexOf('{') === 0) {
    const triggers = JSON.parse(triggerBody)
    for (const eventName in triggers) {
      if (triggers.hasOwnProperty(eventName)) {
        let detail = triggers[eventName]
        if (typeof detail === 'object' && detail !== null) {
          elt = detail.target !== undefined ? detail.target : elt
        } else {
          detail = { value: detail }
        }
        htmx.trigger(elt, eventName, detail)
      }
    }
  } else {
    const eventNames = triggerBody.split(',')
    for (let i = 0; i < eventNames.length; i++) {
      htmx.trigger(elt, eventNames[i].trim(), {})
    }
  }
}

function pushUrlIntoHistory(path) {
  // remove the cache buster parameter, if any
  if (htmx.config.getCacheBusterParam) {
    path = path.replace(/org\.htmx\.cache-buster=[^&]*&?/, '')
    if (path.endsWith('&') || path.endsWith('?')) {
      path = path.slice(0, -1)
    }
  }
  if (htmx.config.historyEnabled) {
    history.pushState({ htmx: true }, '', path)
  }
  if (api.canAccessLocalStorage()) {
    sessionStorage.setItem('htmx-current-path-for-history', path)
  }
}

but it would be nicer once my change in #3404 merges as then push to history would be trivial.