---
name: "up.history"
area: "API"
kind: "module"
parent: "API reference"
url: "https://unpoly.com/api/up.history"
---
<nav aria-label="Unpoly docs">[All docs](https://unpoly.com/index.md) · [API reference](https://unpoly.com/api.md)</nav>

# `up.history`

Features to update the browser history and handle the Back button.

[`up.history.location`](https://unpoly.com/api/up.history.location.md) is the current URL as Unpoly sees it, and [`up:location:changed`](https://unpoly.com/api/up:location:changed.md) is emitted whenever it changes, for example to track page views. When the user goes back, [`up:location:restore`](https://unpoly.com/api/up:location:restore.md) is emitted before Unpoly fetches the restored URL and renders it; listeners can prevent this to handle restoration themselves. An [`[up-back]`](https://unpoly.com/api/up-back.md) link points to the previous URL. To change history from your own code, call [`up.history.push()`](https://unpoly.com/api/up.history.push.md) or [`up.history.replace()`](https://unpoly.com/api/up.history.replace.md).

<nav aria-label="Guides">

- [Learn: History](https://unpoly.com/learn/history.md)

</nav>

---

## Features {#features}

- ### [[up-back]](https://unpoly.com/api/up-back.md) (HTML attribute)

  Changes the link's destination so it points to the previous URL.

- ### [up.history.config](https://unpoly.com/api/up.history.config.md) (Configuration object)

  Configures behavior when the user goes back or forward in browser history.

- ### [up.history.isLocation(url, [options])](https://unpoly.com/api/up.history.isLocation.md) (JavaScript function)

  Returns whether the given URL matches the current browser location.

- ### [up.history.location](https://unpoly.com/api/up.history.location.md) (JavaScript property)

  Returns a normalized URL for the current browser location.

- ### [up.history.previousLocation](https://unpoly.com/api/up.history.previousLocation.md) (JavaScript property)

  Returns a normalized URL for the previous history entry.

- ### [up.history.push(url)](https://unpoly.com/api/up.history.push.md) (JavaScript function) (experimental)

  Adds a new history entry and updates the browser's address bar.

- ### [up.history.replace(url)](https://unpoly.com/api/up.history.replace.md) (JavaScript function) (experimental)

  Replaces the current history entry and updates the browser's location bar.

- ### [up.history.url()](https://unpoly.com/api/up.history.url.md) (JavaScript function) (deprecated)

  Returns a normalized URL for the current history entry.

- ### [up:location:changed](https://unpoly.com/api/up:location:changed.md) (DOM event)

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

- ### [up:location:restore](https://unpoly.com/api/up:location:restore.md) (DOM event)

  This event is emitted when the user is restoring a previous history entry, usually by pressing the back button.

- ### [[up-meta]](https://unpoly.com/api/up-meta.md) (HTML attribute)

  Configures whether this `<head>` element is updated during history changes.