--- 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: 2026-04 source_url: html: >- https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/platform-apis/navigation-api md: >- https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/platform-apis/navigation-api.md --- # 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/latest#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://`: 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://` when workflows span multiple extensions. ### Support Targets (24) ### Supported targets * [customer-account.​footer.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/footer#footer-render-after-) * [customer-account.​order-index.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-index-announcement-) * [customer-account.​order-index.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-index-block-) * [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#order-status-announcement-) * [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#order-status-block-) * [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/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/2026-04/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/2026-04/targets/order-status#customer-information-render-after-) * [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/fulfillment-status#fulfillment-status-targets) * [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/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/2026-04/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/2026-04/targets/fulfillment-status#unfulfilled-items-render-after-) * [customer-account.​order.​action.​menu-item.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-action-menu-item-) * [customer-account.​order.​action.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-action-) * [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/full-page#order-specific-full-page-) * [customer-account.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/full-page#customer-account-full-page-) * [customer-account.​profile.​addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-default#profile-page-default-targets-) * [customer-account.​profile.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-default#profile-announcement-) * [customer-account.​profile.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-default#profile-block-) * [customer-account.​profile.​company-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/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/2026-04/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/2026-04/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/2026-04/targets/profile-page-b2b#company-location-staff-render-after-) * customer-account.​profile.​payment.​render-after ### Properties The global `navigation` object provides navigation functionality for customer account extensions. Access the following properties on the `navigation` object to navigate between pages, manage history, and handle navigation events. * **addEventListener** **(type: "currententrychange", cb: (event: NavigationCurrentEntryChangeEvent) => void) => void** **required** Registers a listener that fires whenever the current navigation entry changes, such as when the buyer navigates to a different page. * **currentEntry** **NavigationHistoryEntry** **required** The current navigation history entry, representing the page the buyer is viewing. Only available in full-page extensions. * **navigate** **NavigateFunction** **required** Navigates to a URL, updating any provided state in the history entries list. Supports [custom protocols](https://shopify.dev/docs/api/customer-account-ui-extensions/latest#custom-protocols) for navigating within customer accounts. * **removeEventListener** **(type: "currententrychange", cb: (event: NavigationCurrentEntryChangeEvent) => void) => void** **required** Removes a previously registered `currententrychange` listener. * **updateCurrentEntry** **(options: NavigationUpdateCurrentEntryOptions) => void** **required** Updates the state of the current history entry without triggering a navigation. Use this when the state change is independent of a page transition, such as saving form progress. ### NavigationCurrentEntryChangeEvent The event object passed to \`currententrychange\` listeners when the current navigation entry changes. * from The history entry the buyer navigated away from. ```ts NavigationHistoryEntry ``` * navigationType The type of navigation that caused the change: \`'push'\`, \`'replace'\`, or \`'traverse'\`. ```ts NavigationTypeString ``` ### NavigationHistoryEntry A single entry in the navigation history stack. Each entry has a unique key, a URL, and optional developer-defined state. * getState Returns a clone of the developer-defined state associated with this history entry. ```ts () => unknown ``` * key A unique, platform-generated identifier for this entry's position in the history stack. This value identifies the slot, not the content. ```ts string ``` * url The URL associated with this history entry, or \`null\` if unavailable. ```ts string | null ``` ### NavigationTypeString An enumerated value representing the type of navigation. ```ts 'push' | 'replace' | 'traverse' ``` ### NavigateFunction A callable function that navigates to a URL within customer accounts. Accepts a destination URL and optional navigation options. ### NavigationNavigateOptions Options passed to \`Navigation.navigate()\` to control history behavior and attach state to the navigation entry. * history An enumerated value that sets the history behavior of this navigation. ```ts 'auto' | 'push' | 'replace' ``` * state Developer-defined information to be stored in the associated NavigationHistoryEntry once the navigation is complete, retrievable via getState(). ```ts unknown ``` ### NavigationUpdateCurrentEntryOptions Options for \`Navigation.updateCurrentEntry()\`. Use this to update the state of the current history entry without triggering a navigation. * state Developer-defined state to associate with the current navigation history entry. ```ts unknown ``` Examples ### 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 ```tsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default async () => { render(, document.body); }; function Extension() { return ( { shopify.navigation.navigate('extension://orders'); }} > Navigate to orders path ); } ``` * #### ##### 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 ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default async () => { render(, document.body); }; function Extension() { return ( { shopify.navigation.navigate( 'shopify:customer-account/orders', ); }} > View all orders { shopify.navigation.navigate( 'shopify:customer-account/profile', ); }} > Edit profile ); } ``` * #### ##### Description Deep-link to a different installed extension using the \`extension://\\` protocol. This example navigates to a loyalty rewards extension when the customer clicks a button in a banner. ##### jsx ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default async () => { render(, document.body); }; function Extension() { function handleNavigate() { shopify.navigation.navigate( 'extension://loyalty-rewards', ); } return ( You have 1,200 points available. View rewards ); } ``` *** ## Best practices * **Use custom protocols instead of absolute URLs**: Always use `extension://`, `shopify:customer-account/`, or `extension://` 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://` 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. ***