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

# up.history.push(url)

**This feature is experimental**. Please [share](https://github.com/unpoly/unpoly/discussions) your experiences so we know what to keep or change.

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

Does not add a history entry if the given URL is already the current browser location. If the URL did change, an [`up:location:changed`](https://unpoly.com/api/up:location:changed.md) event is emitted.

When [navigating](https://unpoly.com/learn/navigation-defaults.md) (or rendering with [`{ history: true }`](https://unpoly.com/api/up.render.md#options.history)), Unpoly will update the browser location for you. You only need to call `up.history.push()` to push a new entry without rendering.

<nav aria-label="Contents">

#### Contents

- [Restoration](#restoration)
- [When history is turned off](#when-history-is-turned-off)
- [Parameters](#parameters)

</nav>

## Restoration {#restoration}

The new history entry will be owned by Unpoly. When the user navigates back to this history entry, Unpoly will [restore the content](https://unpoly.com/learn/restoring-history.md) at that URL.

To push a history entry that you want to restore yourself, use the browser's [`history.pushState()`](https://developer.mozilla.org/en-US/docs/Web/API/History/pushState) function or handle the [`up:location:changed`](https://unpoly.com/api/up:location:changed.md) event.

## When history is turned off {#when-history-is-turned-off}

This function does nothing when [`up.history.config.enabled`](https://unpoly.com/api/up.history.config.md#config.enabled) excludes the `'location'` aspect. See [Turning off history aspects](https://unpoly.com/learn/updating-history.md#disabling).

---

## Parameters {#parameters}

### url {#url}

(required)

The URL for the history entry to be added.

Type: string