Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

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 (25)

Supported targets

Anchor to PropertiesProperties

The navigation object available to all customer account extension targets. Access the following properties to navigate between pages and handle navigation events.

Anchor to navigate navigate required: Navigates to a specific URL within the customer account, updating the history entries list.

Additional navigation properties available only to full-page extensions (customer-account.page.render). Includes access to the current navigation entry and history state.

Anchor to addEventListener addEventListener (type: "currententrychange", cb: (event: ) => void) => void required: Registers a callback that fires whenever the current navigation entry changes.
Anchor to currentEntry currentEntry required: Returns a NavigationHistoryEntry representing the location the user is currently navigated to.
Anchor to navigate navigate required: Navigates to a specific URL within the customer account, updating the history entries list.
Anchor to removeEventListener removeEventListener (type: "currententrychange", cb: (event: ) => void) => void required: Removes a previously registered currententrychange event listener.
Anchor to updateCurrentEntry updateCurrentEntry (options: { state: Record<string, any>; }) => void required: Updates the state of the current entry without triggering a navigation or reload.

NavigationCurrentEntryChangeEvent

The event object for the `currententrychange` event, which fires when `Navigation.currentEntry` has changed. Based on the [Navigation API `NavigationCurrentEntryChangeEvent`](https://developer.mozilla.org/en-US/docs/Web/API/NavigationCurrentEntryChangeEvent) interface.

from
The `NavigationHistoryEntry` that was navigated from.
```
NavigationHistoryEntry
```
navigationType
The type of navigation that resulted in the change.
```
NavigationType
```

NavigationHistoryEntry

Represents a single navigation history entry. Based on the [Navigation API `NavigationHistoryEntry`](https://developer.mozilla.org/en-US/docs/Web/API/NavigationHistoryEntry) interface.

getState
Returns a clone of the developer-supplied state associated with this history entry.
```
() => Record<string, any>
```
key
A unique, user-agent-generated value that represents the history entry's slot in the entries list, rather than the entry itself.
```
string
```
url
The URL of this history entry.
```
string
```

NavigationType

An enumerated value representing the type of navigation: - `'push'`: A new entry is added to the history stack. - `'replace'`: The current entry in the history stack is replaced. - `'traverse'`: The user navigated to an existing entry in the history stack (back or forward).

'push' | 'replace' | 'traverse'

Anchor to useNavigationCurrentEntry
useNavigationCurrentEntry()

Returns the current navigation history entry, representing the page the buyer is viewing. Only available in full-page extensions.

Anchor to useNavigationCurrentEntry-returnsReturns

Examples

import {

reactExtension,

useApi,

Button,

} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(

'customer-account.page.render',

() => <App />,

);

function App() {

const {navigation} = useApi();

return (

<Button

onPress={() => {

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

}}

Navigate to orders path

</Button>

);

}

Examples

Navigate to an extension route

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.

React

import {
  reactExtension,
  useApi,
  Button,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
  'customer-account.page.render',
  () => <App />,
);

function App() {
  const {navigation} = useApi();

  return (
    <Button
      onPress={() => {
        navigation.navigate('extension://orders');
      }}
    >
      Navigate to orders path
    </Button>
  );
}

TS

import {
  extension,
  Button,
} from '@shopify/ui-extensions/customer-account';

export default extension(
  'customer-account.page.render',
  (root, {navigation}) => {
    const button = root.createComponent(
      Button,
      {
        onPress: () => {
          navigation.navigate(
            'extension://orders',
          );
        },
      },
      'Navigate to orders path',
    );
    root.appendChild(button);
  },
);

Navigate to a customer account page

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.

React

import {
  reactExtension,
  useApi,
  InlineStack,
  Button,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
  'customer-account.order-status.block.render',
  () => <Extension />,
);

function Extension() {
  const {navigation} = useApi();

  return (
    <InlineStack>
      <Button
        onPress={() => {
          navigation.navigate(
            'shopify:customer-account/orders',
          );
        }}
      >
        View all orders
      </Button>
      <Button
        onPress={() => {
          navigation.navigate(
            'shopify:customer-account/profile',
          );
        }}
      >
        Edit profile
      </Button>
    </InlineStack>
  );
}

TS

import {
  extension,
  InlineStack,
  Button,
} from '@shopify/ui-extensions/customer-account';

export default extension(
  'customer-account.order-status.block.render',
  (root, {navigation}) => {
    const ordersButton = root.createComponent(
      Button,
      {
        onPress: () => {
          navigation.navigate(
            'shopify:customer-account/orders',
          );
        },
      },
      'View all orders',
    );

    const profileButton = root.createComponent(
      Button,
      {
        onPress: () => {
          navigation.navigate(
            'shopify:customer-account/profile',
          );
        },
      },
      'Edit profile',
    );

    const stack = root.createComponent(
      InlineStack,
      {},
      [ordersButton, profileButton],
    );

    root.appendChild(stack);
  },
);

Navigate to another extension

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.

React

import {
  reactExtension,
  useApi,
  Banner,
  Text,
  Button,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
  'customer-account.order-status.block.render',
  () => <Extension />,
);

function Extension() {
  const {navigation} = useApi();

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

  return (
    <Banner title="Loyalty program">
      <Text>
        You have 1,200 points available.
      </Text>
      <Button onPress={handleNavigate}>
        View rewards
      </Button>
    </Banner>
  );
}

TS

import {
  extension,
  Banner,
  Text,
  Button,
} from '@shopify/ui-extensions/customer-account';

export default extension(
  'customer-account.order-status.block.render',
  (root, {navigation}) => {
    const text = root.createComponent(
      Text,
      {},
      'You have 1,200 points available.',
    );

    const button = root.createComponent(
      Button,
      {
        onPress: () => {
          navigation.navigate(
            'extension://loyalty-rewards',
          );
        },
      },
      'View rewards',
    );

    const banner = root.createComponent(
      Banner,
      {title: 'Loyalty program'},
      [text, button],
    );

    root.appendChild(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?

Anchor to Use casesUse cases

Supported targets

Supported targets

Anchor to PropertiesProperties

NavigateFunction

NavigationCurrentEntryChangeEvent

NavigationHistoryEntry

NavigationType

Anchor to useNavigationCurrentEntryuseNavigationCurrentEntry()

Anchor to useNavigationCurrentEntry-returnsReturns

Anchor to Best practicesBest practices

Anchor to LimitationsLimitations

Anchor to useNavigationCurrentEntry
useNavigationCurrentEntry()