---
name: "up.history.replace"
area: "API"
kind: "JavaScript function"
parent: "up.history module"
visibility: "experimental"
url: "https://unpoly.com/api/up.history.replace"
---
<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.replace(url)

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

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

<nav aria-label="Contents">

#### Contents

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

</nav>

## Restoration {#restoration}

The replaced 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 replace a history entry that you want to restore yourself, use the browser's [`history.replaceState()`](https://developer.mozilla.org/en-US/docs/Web/API/History/replaceState) 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)

Type: string