> Markdown version of [History API](https://vaadin.com/docs/v14/flow/advanced/tutorial-history-api). Section index: [llms.txt](https://vaadin.com/docs/v14/flow/llms.txt)

# History API

The *History API* allows you to access the browser navigation history from the server-side. It also allow you to modify the navigation history by adding a new entry to it or chaging the current entry. E.g. you can change the current URL that is shown in the brower address bar without invoke any navigation. The history is always bound to the current browser window / frame, so you can access it through the *Page* object (available through the *UI*).

```java
History history = UI.getCurrent().getPage().getHistory();
```

## <a id="traversing-history"></a>Traversing History

With the methods `forward()`, `back()` and `go(int)` you can programmatically traverse the browser’s history entries. The methods correspond to the user actions on the browser’s back and forward buttons.

```java
history.back(); // navigates back to the previous entry

history.forward(); // navigates forward to the next entry

history.go(-2); // navigates back two entries
history.go(1); // equal to history.forward();
history.go(0); // will reload the current page
```

> **Note:** Triggering the `forward`, `back` and `go` methods will asynchronously trigger a *HistoryStateChangeEvent* if the history entries are for the same document, e.g. the entries share the [same origin](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy).

## <a id="handling-user-navigation"></a>Handling user navigation

If you want to manually handle navigation events you can replace it by setting a handler for navigation events using the `history.setHistoryStateChangeHandler(HistoryStateChangeHandler)`. It will be notified when:

- the user navigates back or forward using the browser buttons

- the navigation was done programmatically from server-side java code or client-side JavaScript

- the user clicks a link marked with the *router-link* attribute

```java
history.setHistoryStateChangeHandler(this::onHistoryStateChange);

private void onHistoryStateChange(HistoryStateChangeEvent event) {
    // site base url is www.abc.com/
    // user navigates back from abc.com/dashboard to abc.com/home
    event.getLocation().getPath(); // returns "home"
}
```

> **Note:** The server side history state change event is not fired if only the [hash](https://developer.mozilla.org/en-US/docs/Web/Events/hashchange) has changed. Hash is always stripped from the location sent to server. Hash is a browser feature not intended for use on the server side.

## <a id="changing-history"></a>Changing history

You can update the history by either pushing new entries to the history, or by replacing the current entry. You may optionally provide a json value as the *state* parameter. This state value will be available via `LocationChangeEvent:getState()` when the entry is being revisited the next time.

```java
// adds a new history entry for location "home", no state
history.pushState(null, "home");

// replaces the current entry with location "about" and a state object
JsonValue state = Json.create("preview-mode");
history.replaceState(state, "about");
```

> **Note:** The *url* used with `pushState` and `replaceState` must be for the [same origin](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) as the current *url*; otherwise browser will throw an exception and the history is not updated.

> **Note:** If you use either `pushState` or `replaceState`, the framework internal scroll position restoration on navigation won’t work, since it stores data in the `history.state` to keep track of the scroll positions.

`D79D885C-4D24-46F7-BB7B-17A5DFC40255`