Unpoly will update the browser location as the user follows links and submits forms.
However there are some restrictions for when Unpoly will change history. This page explains the reasons for these restrictions and shows how to override them.
By default Unpoly only changes history when a main element is rendered. This is to prevent location changes when rendering a minor fragment, like a table row or a message counter.
This behavior is a navigation default in
up.fragment.config.navigateOptions.history === 'auto'
.
To cause auto-history to trigger on fragments other than main elements, add a selector to up.fragment.config.autoHistoryTargets
.
To force a location change, use one of the following:
[up-history=true]
attribute on your link or form.{ history: true }
option when rendering a fragment programmatically.up.fragment.config.navigateOptions.history = true
. This will be the new default for all links and forms.To prevent a location change after rendering a major fragment, use one of the following:
[up-history=false]
attribute on your link or form.{ history: false }
option when rendering a fragment programmatically.up.fragment.config.navigateOptions.history = false
. This will be the new default for all links and forms.GET
requests change historyOnly requests with a GET
method are egible to change browser history.
This is because only GET
requests can be reloaded and restored safely.
This behavior cannot be configured.
This restrictions means form submissions with methods like POST
, PUT
or PATCH
never change history.
However, if a successful form submssion redirects to a GET
URL, that new request is
again egible to change history.
By default modals and overlays will have visible history if their initial fragment is a main element. To override this default, use one of the following:
[up-history]
attribute on a link or form that opens an overlay.{ history }
option to up.layer.open()
or up.layer.ask()
.up.layer.config.overlay.history
. This will be the new
default for new overlays. You may also configure different defaults for different layer modes,
e.g. by setting up.layer.configure.popup.history
.Also see History restoration in overlays
When an overlay has visible history, its location is shown in the browser's address bar while the overlay is open.
When an overlay is closed, the URL from the background layer is restored.
If visible history is disabled, it will remain disabled for the lifetime of the overlay.
Even when an overlay doesn't have visible history, is still tracks its location using the rules described
on this page. You can access an overlay's current location using up.layer.location
.
When your JavaScript updates a fragment using up.render()
, history is never changed by default.
You may opt into history changes using one of the following:
{ history: true }
option to force a history change.{ history: 'auto' }
option to update history if updating a major fragment.up.navigate()
instead of up.render()
to inherit navigation defaults.See Restoring history.