Navigation API
The Navigation API lets you navigate within and outside of your app using the HTML anchor element. You can also modify the top-level browser URL with or without navigating using the History API or the browser's native Navigation API.
Anchor to Use casesUse cases
- App routing: Navigate between pages within your app using HTML anchor elements.
- URL management: Modify the top-level browser URL without triggering full page navigation.
- External links: Navigate to external pages or Shopify admin pages from within your app.
- Programmatic navigation: Navigate to routes using JavaScript with
open()for cases where anchor elements aren't suitable.
html
Examples
Description
Navigate to Shopify admin pages. This example uses the `shopify:` protocol to navigate to admin index pages (products, orders, customers) or directly to specific resources by appending the resource ID.
html
<!-- Index pages --> <a href="shopify://admin/products" target="_top">Products</a> <a href="shopify://admin/orders" target="_top">Orders</a> <a href="shopify://admin/customers" target="_top">Customers</a> <!-- Specific resources --> <a href="shopify://admin/products/123" target="_top">Product #123</a> <a href="shopify://admin/orders/456" target="_top">Order #456</a> <a href="shopify://admin/customers/789" target="_top">Customer #789</a>Description
Navigate to a relative path in your app. This example navigates to a route within your app using a relative path. Use anchor elements or `window.open()` with paths relative to your app root.
HTML
<a href="/settings">Settings</a>JavaScript
open('/settings', '_self');Description
Update the browser URL with the History API. This example uses `history.pushState()` and `history.replaceState()` to update the browser URL without triggering a page reload. Use `pushState` to add a new history entry, or `replaceState` to modify the current entry.
pushState
history.pushState(null, '', '/settings');replaceState
history.replaceState(null, '', '/settings');Description
Update the browser URL with the Navigation API. This example uses `navigation.navigate()` with history options to update the browser URL. The Navigation API provides a more modern alternative to the History API with better support for SPA routing.
pushState
navigation.navigate('/settings', { history: 'push', });replaceState
navigation.navigate('/settings', { history: 'replace', });Description
Open an external URL in a new window. This example opens an external URL in a new browser tab or window using `target="_blank"`. The Shopify admin remains open in the original tab.
HTML
<a href="https://example.com" target="_blank">Settings</a>JavaScript
open('https://example.com', '_blank');Description
Open an external URL in the current window. This example navigates to an external URL in the current window using `target="_top"`. The browser leaves the Shopify admin and loads the external page.
HTML
<a href="https://example.com">Settings</a>JavaScript
open('https://example.com', '_top');