---
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: v1.0
source_url:
  html: >-
    https://shopify.dev/docs/api/app-home/latest/apis/user-interface-and-interactions/navigation-api
  md: >-
    https://shopify.dev/docs/api/app-home/latest/apis/user-interface-and-interactions/navigation-api.md
api_name: app-home
---

# Navigation API

**Info:**

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](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a). You can also modify the top-level browser URL with or without navigating using the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) or the browser's native [Navigation API](https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API).

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

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

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

  ```html
  <a href="/settings">Settings</a>
  ```

  ##### JavaScript

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

  ```js
  history.pushState(null, '', '/settings');
  ```

  ##### replaceState

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

  ```js
  navigation.navigate('/settings', {
    history: 'push',
  });
  ```

  ##### replaceState

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

  ```html
  <a href="https://example.com" target="_blank">Settings</a>
  ```

  ##### JavaScript

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

  ```html
  <a href="https://example.com">Settings</a>
  ```

  ##### JavaScript

  ```js
  open('https://example.com', '_top');
  ```

***