Navigation API
App Bridge isn't versioned with Polaris. App Bridge APIs and web components are identical in every App Home reference version.
App Bridge isn't versioned with Polaris. App Bridge APIs and web components are identical in every App Home reference version.
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');