> Note:
> This is a legacy API. Use the latest version of the App Bridge [History](/docs/api/app-bridge-library/apis/navigation) instead.
The `History` action set allows you to use the JavaScript History API to modify the top-level browser URL without navigating. Use the `History` action set to update the top-level browser URL to match your app.
You can use the history action in the following ways:
1. [Plain JavaScript](#plain-javascript)
2. [React hook](#react)
## Plain JavaScript
### Example code
Import the `createApp` function from `@shopify/app-bridge` and the `History` action from `@shopify/app-bridge/actions`. Then use the `createApp` function to create an app.
> Note
> In the following example, `config` is a valid App Bridge configuration object. Learn more about [configuring App Bridge](/docs/api/app-bridge/previous-versions/app-bridge-from-npm/app-setup#initialize-shopify-app-bridge-in-your-app).
```js
import createApp from '@shopify/app-bridge';
import {History} from '@shopify/app-bridge/actions';
const app = createApp(config);
const history = History.create(app);
```
### Push a new history entry containing the relative app path
The path is relative to the app origin and must be prefixed with a slash. Adding a history entry does not redirect the app.
```js
// Pushes {appOrigin}/settings to the history
history.dispatch(History.Action.PUSH, '/settings');
```
### Replace the current history entry with the relative app path
The path is relative to the app origin and must be prefixed with a slash. Replacing the history entry does not redirect the app:
```js
// Replaces the current history url with {appOrigin}/settings
history.dispatch(History.Action.REPLACE, '/settings');
```
### Subscribe to actions
You can subscribe to actions dispatched through the specific history action set:
```js
history.subscribe(History.Action.REPLACE, (payload: History.Payload) => {
// Do something with the history replace action
console.log(`Updated the history entry to path: ${payload.path}`);
});
history.subscribe(History.Action.PUSH, (payload: History.Payload) => {
// Do something with the history push action
console.log(`Added a history entry with the path: ${payload.path}`);
});
```
### Subscribe to all history actions
You can subscribe to all history actions, regardless of which action sets trigger the actions:
```js
app.subscribe(History.Action.REPLACE, (payload: History.Payload) => {
// Do something with the history replace action
console.log(`Updated the history entry to path: ${payload.path}`);
});
app.subscribe(History.Action.PUSH, (payload: History.Payload) => {
// Do something with the history push action
console.log(`Added a history entry with the path: ${payload.path}`);
});
```
## React
The `useNavigationHistory` hook enables you to modify the top-level browser URL to match your app location. It uses the browser [history API](https://developer.mozilla.org/en-US/docs/Web/API/History) and modifies the URL without navigating.
The `useNavigationHistory` hook accepts no props and returns `push` and `replace` methods.
### Example code
> Note
> When using the App Bridge React library, you need to wrap all of your App Bridge React code inside of a single App Bridge [`Provider`](/docs/api/app-bridge/previous-versions/app-bridge-from-npm/using-react#provider).
Add a new location to the history stack with `push`.
```jsx
import {useNavigationHistory} from '@shopify/app-bridge-react';
function MyComponent {
const {push} = useNavigationHistory();
return (
);
}
```
Replace the current location in the history stack with `replace`.
```jsx
import {useNavigationHistory} from '@shopify/app-bridge-react';
function MyComponent {
const {replace} = useNavigationHistory();
return (
);
}
```
### Props
The `useNavigationHistory` hook does not accept any arguments. The APIs for the `push` and `replace` methods are as follows:
#### `push`
|Name|Type|Description|Required|
|---|---|---|---|
|location|`string`|Path to add to history stack |Yes|
#### `replace`
|Name|Type|Description|Required|
|---|---|---|---|
|location|`string`|Path to replace current loaction in history stack |Yes|