Learn History in overlays

An overlay can show its own URL in the browser's address bar while it is open, or leave the address bar on the page behind it. By default an overlay shows its URL when it contains the main fragment, so a page opened in a modal gets a shareable address while a small popup menu does not. This setting is called the overlay's history visibility. You can override it globally or for individual overlays.

Overlays with visible history

When an overlay has visible history, its location and title are shown in the browser window while the overlay is open. Meta tags from the overlay content are placed into the <head>.

In the example below, we start with a root layer at /:

location.pathname // result: "/"

We now open an overlay from /users/5. Its content is a main fragment, so the overlay has visible history. Note how its URL is reflected in the browser's address bar:

await up.layer.open({ url: '/users/5' })
location.pathname // result: "/users/5"

Each layer still tracks its own location:

up.layer.current.location // result: "/users/5"
up.layer.root.location    // result: "/"

When the overlay is closed, the root layer's URL, title and meta tags are restored:

await up.layer.dismiss()
location.pathname // result: "/"

Hiding an overlay's history

By default an overlay has visible history when its initial fragment is a main fragment. This shows the location of significant content to the user, but hides the internal location of smaller popups or menus.

To hide the history of one overlay, set an [up-history=false] attribute on the link or form that opens it:

<a href="/users/5" up-layer="new" up-history="false">Show user</a> <!-- mark: up-history="false" -->

When opening an overlay from JavaScript, pass a { history: false } option to up.layer.open() or up.layer.ask(). Setting true instead of false makes an overlay show its history even when its content is not a main fragment.

To change the default for all overlays, configure up.layer.config.overlay.history. A mode can have its own default, like up.layer.config.popup.history for all popups. Links and options still override the configured default.

The root layer always has visible history. This cannot be configured.

Behavior with invisible history

When an overlay's history is hidden, nothing the overlay renders is reflected in the address bar, the window title or the document <head>, for as long as the overlay is open.

In the example below, we open an overlay from /users/5 with invisible history. Note how the browser's address bar stays on the root layer's location:

location.pathname // result: "/"
await up.layer.open({ url: '/users/5', history: false }) // mark: history: false
location.pathname // result: "/"

The overlay still tracks its own location, which you can read from its up.Layer#location property:

up.layer.current.location // result: "/users/5"
up.layer.root.location    // result: "/"

Observe up:layer:location:changed to be notified when a layer's location changes. Unlike up:location:changed, this event is also emitted for layers with invisible history.

Navigation bars work with invisible history

History visibility is not required for .up-current classes to be set. When a navigation bar looks for links pointing to the current page, it compares a link's [href] with the location of its own layer, not with the address bar.

Invisible history is inherited

When an overlay with invisible history opens another overlay, the nested overlay also has invisible history. The nested overlay cannot override this with [up-history=true] or { history: true }.

When a link in an overlay updates the address bar

Once an overlay is open, links and forms inside it follow the usual rules for when history is updated: a link updates history when it targets the main fragment, or when it sets [up-history=true]. The address bar only changes when both the link updates history and the updated layer has visible history:

When a link updates another layer, only the history visibility of the targeted layer is considered. The visibility of the link's own layer is not relevant.

Going back while an overlay is open

When the user presses Back, Unpoly closes all overlays and renders the restored URL as a full page in the root layer.

Which URL the browser goes back to depends on whether the overlay added a history entry. Say the user went from /home to /projects, then opened /users/5 in an overlay:

This is often an acceptable default, since every route in an Unpoly app can render a full page anyway. Subinteractions in particular work the same on the root layer and in an overlay.

If you cannot work with this, you have the following options:

• Hide the history of all overlays with up.layer.config.overlay.history = false. Then no overlay ever adds a history entry.
• Implement a custom restoration behavior.