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.

Examples

html

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

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

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');
```

Was this page helpful?