Choose a version:

Navigation API

The Navigation API lets you navigate between extension routes, other extensions, or host pages within customer accounts. Use this API to build multi-route extensions, link to specific customer account pages, or direct customers to other installed extensions.

The API supports several custom protocols:

shopify:customer-account/: Navigates to built-in customer account host pages such as orders or profile.
extension://: Navigates within the current extension's routes.
extension://<handle>: Navigates to a different installed extension by its handle.

Anchor to Use casesUse cases

Build multi-page extensions: Use extension:// routes to create extensions with multiple views, such as a subscription management page with a settings sub-page.
Link to customer account pages: Navigate customers to built-in pages like order details or profile settings using the shopify:customer-account/ protocol.
Connect related extensions: Deep-link from one extension to another using extension://<handle> when workflows span multiple extensions.

Support

Targets (24)

Supported targets

Anchor to PropertiesProperties

The shopify global object provides the navigation interface for customer account extensions. Access the following properties on shopify.navigation to navigate between pages, manage history, and handle navigation events.

Anchor to addEventListener addEventListener (type: "currententrychange", cb: (event: ) => void) => void required: Registers a listener that fires when the current history entry changes.
Anchor to currentEntry currentEntry required: The location the user is currently navigated to.
Anchor to navigate navigate required: Navigates to a specific URL, updating any provided state in the history entries list.
Anchor to removeEventListener removeEventListener (type: "currententrychange", cb: (event: ) => void) => void required: Removes a previously registered currententrychange listener.
Anchor to updateCurrentEntry updateCurrentEntry (options: ) => void required: Updates the state of the current entry without performing a navigation or reload.

NavigationCurrentEntryChangeEvent

The NavigationCurrentEntryChangeEvent interface of the Navigation API is the event object for the currententrychange event, which fires when the Navigation.currentEntry has changed.

from
Returns the NavigationHistoryEntry that was navigated from.
```
NavigationHistoryEntry
```
navigationType
Returns the type of the navigation that resulted in the change.
```
NavigationTypeString
```

NavigationHistoryEntry

The NavigationHistoryEntry interface of the Navigation API represents a single navigation history entry.

getState
Returns a clone of the available state associated with this history entry.
```
() => unknown
```
key
Returns the key of the history entry. This is a unique, UA-generated value that represents the history entry's slot in the entries list rather than the entry itself.
```
string
```
url
Returns the URL of this history entry.
```
string | null
```

NavigationTypeString

An enumerated value representing the type of navigation.

'push' | 'replace' | 'traverse'

NavigateFunction

A function that navigates to a specific URL, optionally configuring history behavior and custom state.

NavigationUpdateCurrentEntryOptions

Options for updating the state of the current navigation history entry without performing a navigation.

state
```
unknown
```

Examples

jsx

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

export default async () => {

render(<Extension />, document.body);

};

function Extension() {

return (

<s-button

onClick={() => {

navigation.navigate('extension://orders');

}}

Navigate to orders path

</s-button>

);

}

Examples

Description

Navigate to a route within the current extension using the `extension://` protocol. This example renders a button that navigates to the `orders` path inside the extension when clicked.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  return (
    <s-button
      onClick={() => {
        navigation.navigate('extension://orders');
      }}
    >
      Navigate to orders path
    </s-button>
  );
}

Description

Link to built-in customer account pages using the `shopify:customer-account/` protocol. This example renders buttons that navigate to the orders list and profile pages.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  return (
    <s-stack direction="inline" gap="base">
      <s-button
        onClick={() => {
          navigation.navigate(
            'shopify:customer-account/orders',
          );
        }}
      >
        View all orders
      </s-button>
      <s-button
        onClick={() => {
          navigation.navigate(
            'shopify:customer-account/profile',
          );
        }}
      >
        Edit profile
      </s-button>
    </s-stack>
  );
}

Description

Deep-link to a different installed extension using the `extension://<handle>` protocol. This example navigates to a loyalty rewards extension when the customer clicks a button in a banner.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  function handleNavigate() {
    navigation.navigate(
      'extension://loyalty-rewards',
    );
  }

  return (
    <s-banner heading="Loyalty program">
      <s-text>
        You have 1,200 points available.
      </s-text>
      <s-button onClick={handleNavigate}>
        View rewards
      </s-button>
    </s-banner>
  );
}

Anchor to Best practicesBest practices

Use custom protocols instead of absolute URLs: Always use extension://, shopify:customer-account/, or extension://<handle> protocols rather than hardcoded URLs. Custom protocols ensure your extension works across different store domains and environments.
Provide a way back: When navigating to sub-routes within your extension, always include a navigation action that lets customers return to the previous view.
Listen for navigation events when rendering depends on the route: Use shopify.navigation.currentEntry or listen for currententrychange events to update your UI when the route changes, rather than relying on stale state.

Anchor to LimitationsLimitations

The Navigation API can only navigate within the customer accounts surface. It can't redirect to external URLs or the storefront.
The extension://<handle> protocol requires the target extension to be installed and active on the store. If the target extension isn't available, the navigation call has no effect.
Navigation between extensions doesn't support passing custom data or query parameters beyond what the target extension's URL structure supports.

Was this page helpful?