---
title: Navigation API
description: >-
  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.
api_version: 2026-07-rc
source_url:
  html: >-
    https://shopify.dev/docs/api/app-home-ui-extension/latest/target-apis/utility-apis/navigation-api
  md: >-
    https://shopify.dev/docs/api/app-home-ui-extension/latest/target-apis/utility-apis/navigation-api.md
---

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

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

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

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

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

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

  ```html
  <a href="https://example.com/docs" target="_blank">Open in new tab</a>
  <a href="https://example.com" target="_top">Leave admin</a>
  ```

***