---
area: "Learn"
parent: "History chapter"
url: "https://unpoly.com/learn/updating-history"
---
# Updating history
When Unpoly updates a page's main fragment, it also updates the browser's address bar, the window title and the meta tags in the ``. The result looks and behaves like a full page load: the user can bookmark the URL, share it, or return to it with the Back button. Updates to minor fragments leave history untouched.
## When history is updated {#when-history-is-changed}
Following a link or submitting a form counts as [navigation](https://unpoly.com/learn/navigation-defaults.md). When navigation updates the layer's [main fragment](https://unpoly.com/api/main.md), Unpoly adds a history entry for the new URL:
```html
Read post
```
Clicking the link fetches `/posts/5` and swaps the main fragment. The address bar now shows `/posts/5`, and the window title is taken from the response's ``.
A link that updates a smaller fragment does not change history:
```html
<a href="/comments?page=2" up-target="#comments">Next page</a>
```
Clicking this link replaces only the `#comments` element. The address bar keeps its URL, so the user does not collect a history entry for every minor update.
This is the `auto` setting of the [`[up-history]`](https://unpoly.com/api/up-follow.md#up-history) attribute, which is the default for links and forms. History is updated when the targeted fragment contains an element matching [`up.fragment.config.autoHistoryTargets`](https://unpoly.com/api/up.fragment.config.md#config.autoHistoryTargets). By default that is the layer's main fragment. When the new URL is the one already in the address bar, no entry is added.
> #### Note
>
> An overlay only shows its URL in the address bar when it has [visible history](https://unpoly.com/learn/history-in-overlays.md). This page describes the root layer, which always has visible history.
### Forcing or preventing a change {#forcing}
To update history even when a minor fragment is updated, set `[up-history=true]`:
```html
<a href="/comments?page=2" up-target="#comments" up-history="true">Next page</a>
```
To never update history, set `[up-history=false]`:
```html
<a href="/posts/5" up-follow up-history="false">Peek at post</a>
```
Forms accept the same [`[up-history]`](https://unpoly.com/api/up-submit.md#up-history) attribute. When rendering from JavaScript, pass a [`{ history }`](https://unpoly.com/api/up.render.md#options.history) option instead.
To change the default for all links and forms, configure `up.fragment.config.navigateOptions.history`. To decide per link, listen to [`up:link:follow`](https://unpoly.com/api/up:link:follow.md) or [`up:form:submit`](https://unpoly.com/api/up:form:submit.md) and set `event.renderOptions.history`:
```js
up.on('up:link:follow', function(event, link) {
if (link.matches('.pagination a')) {
event.renderOptions.history = false
}
})
```
To stop Unpoly from ever changing history, or only some aspects of it, see [Turning off history aspects](#disabling).
### Treating other fragments as major {#auto-history-targets}
If your app has a significant element that is not the main fragment, you can add its selector to [`up.fragment.config.autoHistoryTargets`](https://unpoly.com/api/up.fragment.config.md#config.autoHistoryTargets):
```js
up.fragment.config.autoHistoryTargets.push('.content')
```
Now a link targeting `.content`, or any fragment that contains a `.content` element, updates history without an explicit `[up-history=true]`.
### Only `GET` requests update history {#get-requests}
Only a `GET` request can be reloaded or restored by the browser, so only a `GET` response updates history. A response to a `POST`, `PUT` or `PATCH` request never changes history, even with `[up-history=true]`.
When a successful submission redirects to a `GET` URL, the redirect's response updates history with the new URL. Unpoly detects the redirect from the response URL, or from an [`X-Up-Method`](https://unpoly.com/api/X-Up-Method.md) header that your server can set.
The exception is an explicit location: when you set [`[up-location]`](https://unpoly.com/api/up-follow.md#up-location) or pass a [`{ location }`](https://unpoly.com/api/up.render.md#options.location) option, Unpoly pushes that URL even after a non-`GET` request.
The same rules apply to error responses. When an error response to a `GET` request renders an error page into the main fragment, the address bar shows its URL, like after a full page load. A form submission that fails with a validation error does not change history. See [Handling error responses](https://unpoly.com/learn/error-responses.md).
### Rendering from JavaScript {#scripting}
The low-level [`up.render()`](https://unpoly.com/api/up.render.md) function never updates history by default:
```js
up.render({ target: '.content', url: '/path' }) // History is unchanged
```
Pass a `{ history }` option to opt in:
```js
up.render({ target: '.content', url: '/path', history: true }) // Always update
up.render({ target: '.content', url: '/path', history: 'auto' }) // Update if the main fragment is rendered
```
To render with all [navigation defaults](https://unpoly.com/learn/navigation-defaults.md#navigation-defaults), including `{ history: 'auto' }`, use [`up.navigate()`](https://unpoly.com/api/up.navigate.md) instead of [`up.render()`](https://unpoly.com/api/up.render.md).
## What is updated {#history-state}
A history update comprises the following:
- The URL shown in the browser's address bar.
- The document title shown as the browser's window title.
- Meta tags like `meta[name=description]` or `link[rel=canonical]`.
- The `[lang]` attribute of the root `<html>` element.
- [JSON-LD](https://json-ld.org/) annotations in the `<head>`.
In the document below, the highlighted nodes are updated when history changes, in addition to the location URL:
```html
<html lang="en">
<head>
<title>Our team · AcmeCorp
...