---
title: Navigation API
description: >-
  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.
api_version: 2025-07
api_name: customer-account-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/platform-apis/navigation-api
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/platform-apis/navigation-api.md
---

Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/apps/build/customer-accounts/migrate-to-web-components) to upgrade your extension.

# 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](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07#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.

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

* Customer​Account::Kitchen​Sink
* [customer-account.​footer.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/footer#footer-render-after-)
* [customer-account.​order-index.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-targets)
* [customer-account.​order-index.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-block-)
* [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-announcement-)
* [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-block-)
* [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-item-render-after-)
* [customer-account.​order-status.​cart-line-list.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-list-render-after-)
* [customer-account.​order-status.​customer-information.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#customer-information-render-after-)
* [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#fulfillment-status-targets)
* [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#payments-and-returns-targets)
* [customer-account.​order-status.​return-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#return-details-render-after-)
* [customer-account.​order-status.​unfulfilled-items.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#unfulfilled-items-render-after-)
* [customer-account.​order.​action.​menu-item.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-menu-item-)
* [customer-account.​order.​action.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-)
* [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#order-specific-full-page-)
* [customer-account.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#customer-account-full-page-)
* [customer-account.​profile.​addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-page-default-targets-)
* [customer-account.​profile.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#announcement-)
* [customer-account.​profile.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-block-)
* [customer-account.​profile.​company-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#profile-page-b2b-targets-)
* [customer-account.​profile.​company-location-addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-addresses-render-after-)
* [customer-account.​profile.​company-location-payment.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-payment-render-after-)
* [customer-account.​profile.​company-location-staff.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-staff-render-after-)
* customer-account.​profile.​payment.​render-after

### Properties

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

* **navigate**

  **NavigateFunction**

  **required**

  Navigates to a specific URL within the customer account, updating the history entries list.

### NavigateFunction

A function that performs navigation to a specific URL within the customer account.



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

* **addEventListener**

  **(type: "currententrychange", cb: (event: NavigationCurrentEntryChangeEvent) => void) => void**

  **required**

  Registers a callback that fires whenever the current navigation entry changes.

* **currentEntry**

  **NavigationHistoryEntry**

  **required**

  Returns a `NavigationHistoryEntry` representing the location the user is currently navigated to.

* **navigate**

  **NavigateFunction**

  **required**

  Navigates to a specific URL within the customer account, updating the history entries list.

* **removeEventListener**

  **(type: "currententrychange", cb: (event: NavigationCurrentEntryChangeEvent) => void) => void**

  **required**

  Removes a previously registered `currententrychange` event listener.

* **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.

  ```ts
  NavigationHistoryEntry
  ```

* navigationType

  The type of navigation that resulted in the change.

  ```ts
  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.

  ```ts
  () => 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.

  ```ts
  string
  ```

* url

  The URL of this history entry.

  ```ts
  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).

```ts
'push' | 'replace' | 'traverse'
```

## use​Navigation​Current​Entry()

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

### Returns

* **NavigationHistoryEntry**

Examples

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

  ```tsx
  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

  ```js
  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

  ```tsx
  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

  ```js
  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

  ```tsx
  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

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

***

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

***

## Limitations

* 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.

***