Choose a version:

Navigation API

App home UI extensions support standard browser navigation APIs. You can use window.location, window.history, and window.navigation directly, so Single Page Application (SPA) routers work without configuration.

Use these protocols when building links or navigating programmatically:

Protocol	Use case	Example
`shopify:admin`	Deep link into the Shopify Admin	`shopify:admin/products/1234567890`
`app:`	Navigate within your app	`app:settings/advanced`
Relative path	Route within your app	`/reviews/${product.id}`

External navigations (Admin back button, deep links) are reflected in window.location automatically.

Anchor to Use casesUse cases

Multi-page apps: Use SPA routing (for example, preact-iso) with relative paths to build multi-page app experiences.
Admin deep links: Link merchants to specific admin pages like products, orders, or settings using the shopify:admin protocol.
URL-driven state: Update the browser URL with history.pushState() or navigation.navigate() to reflect app state without a full page reload.
External resources: Open external URLs in a new tab or the current window.

Examples

html

<a href="shopify:admin/products">All products</a>

<a href="shopify:admin/products/1234567890">Specific product</a>

<a href="shopify:admin/orders">All orders</a>

Examples

Description

Use the `shopify:admin` protocol in anchor elements to link directly to admin pages. Append a resource ID to navigate to a specific resource.

html

<a href="shopify:admin/products">All products</a>
<a href="shopify:admin/products/1234567890">Specific product</a>
<a href="shopify:admin/orders">All orders</a>

Description
Use relative paths to navigate between routes in your app. This works with anchor elements and programmatically with `window.open()`.
html
```
<a href="/settings">App settings</a>
<a href="/discounts/new">Create discount</a>
```
Description
Use `history.pushState()` to update the browser URL without triggering a page reload. Use `replaceState()` when you don't want to create a new history entry.
js
```
history.pushState({}, '', '/discounts/abc123');

history.replaceState({}, '', '/discounts/abc123?tab=rules');
```
Description
Open external URLs in a new tab with `target="_blank"`, or in the current window with `target="_top"`. The Shopify admin stays open when using `_blank`.
html
```
<a href="https://example.com/docs" target="_blank">Open in new tab</a>
<a href="https://example.com" target="_top">Leave admin</a>
```

Was this page helpful?