> 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 (
    <Button onClick={() => {
      push({pathname: '/foo'});
    }}>Push "foo" onto history stack</Button>
  );
}
```

Replace the current location in the history stack with `replace`.

```jsx
import {useNavigationHistory} from '@shopify/app-bridge-react';

function MyComponent {
  const {replace} = useNavigationHistory();

  return (
    <Button onClick={() => {
      replace({pathname: '/bar'});
    }}>Replace current location on the history stack with "bar"</Button>
  );
}
```

### 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|