Edit this page

up.history up:location:changed
DOM event

This event is emitted after the browser's address bar was updated with a new URL.

There may be several reasons why the browser location was changed:

  • A fragment update changes history through navigation or rendering with { history: true }.
  • The user uses the back or forward buttons in their browser UI.
  • Programmatic calls to functions like up.history.push() or history.pushState().
  • The user navigates to a different #hash within the page.

The up:location:changed event is not emitted when the page is loaded initially. For this observe up:framework:booted.

Handling the change

This event cannot be prevented, but you can mutate the event.willHandle property to decide whether Unpoly should handle the change by restoring a location or revealing a fragment matching the location #hash.

Location changes in overlays

Overlays can configure whether their history state is reflected the browser's address bar.

When a layer has no visible history, no up:location:changed event will be emitted. However, an up:layer:location:changed will be emitted even if the address bar did not change.

Also see History in overlays.


Event properties

Change

event.location
required

The new URL after the change.

When this event is emitted, the browser location has already been updated.

string
event.reason
required

The action that caused this change in history state.

The value of this property is one of the following:

Value Reason
'hash' The location was changed, but only the #hash changed from the previous location.
'push' A new history entry was added via up.history.push() or history.pushState().
'replace' The current history update was changed via up.history.replace() or history.replaceState().
'pop' The user navigated back to the current location.
string

Handling

event.alreadyHandled
required

Whether Unpoly thinks this change has already been handled and requires no additional processing.

For example, updating history by navigating or calling history.pushState() is considered to be already handled.

boolean
event.willHandle
required

Whether Unpoly thinks it is responsible for handling this change.

By default Unpoly feels responsible for owned locations when the change has not already been handled.

Listeners can tell Unpoly to not handle a change by setting event.willHandle = false. You can then handle the change with your own code.

Listeners can tell Unpoly to handle a change it does not own by setting event.willHandle = true. Regardless of this Unpoly will never handle a change that already been handled.

boolean