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:adminprotocol. - URL-driven state: Update the browser URL with
history.pushState()ornavigation.navigate()to reflect app state without a full page reload. - External resources: Open external URLs in a new tab or the current window.
html
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>