Skip to main content

History

Note

This is a legacy API. Use the latest version of the App Bridge History 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
  2. React hook

Anchor to Plain JavaScriptPlain JavaScript

Anchor to Example codeExample 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.

import createApp from '@shopify/app-bridge';
import {History} from '@shopify/app-bridge/actions';

const app = createApp(config);

const history = History.create(app);

Anchor to Push a new history entry containing the relative app pathPush 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.

// Pushes {appOrigin}/settings to the history
history.dispatch(History.Action.PUSH, '/settings');

Anchor to Replace the current history entry with the relative app pathReplace 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:

// Replaces the current history url with {appOrigin}/settings
history.dispatch(History.Action.REPLACE, '/settings');

Anchor to Subscribe to actionsSubscribe to actions

You can subscribe to actions dispatched through the specific history action set:

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}`);
});

Anchor to Subscribe to all history actionsSubscribe to all history actions

You can subscribe to all history actions, regardless of which action sets trigger the actions:

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}`);
});

Anchor to ReactReact

The useNavigationHistory hook enables you to modify the top-level browser URL to match your app location. It uses the browser history API and modifies the URL without navigating.

The useNavigationHistory hook accepts no props and returns push and replace methods.

Anchor to Example codeExample 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.

Add a new location to the history stack with push.

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.

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>
);
}

Anchor to PropsProps

The useNavigationHistory hook does not accept any arguments. The APIs for the push and replace methods are as follows:

Anchor to [object Object]push

NameTypeDescriptionRequired
locationstringPath to add to history stackYes

Anchor to [object Object]replace

NameTypeDescriptionRequired
locationstringPath to replace current loaction in history stackYes
Was this page helpful?