---
title: Navigation API
description: >-
  The Navigation API provides web-standard navigation functionality for POS UI
  extensions, allowing you to navigate between URLs, manage navigation history,
  and handle navigation events within modal interfaces. The API is available
  globally as the `navigation` object and follows web platform standards.
api_version: 2025-10
api_name: pos-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/pos-ui-extensions/latest/target-apis/platform-apis/navigation-api
  md: >-
    https://shopify.dev/docs/api/pos-ui-extensions/latest/target-apis/platform-apis/navigation-api.md
---

# Navigation API

The Navigation API provides web-standard navigation functionality for POS UI extensions, allowing you to navigate between URLs, manage navigation history, and handle navigation events within modal interfaces. The API is available globally as the `navigation` object and follows web platform standards.

## NavigationApi

The global `navigation` object provides web-standard navigation functionality. Access these properties and methods directly through the global `navigation` object to manage navigation within modal interfaces.

* back

  () => void

  required

  Navigates to the previous entry in the history list. Use for implementing back buttons, breadcrumb navigation, or allowing users to return to previous screens in multi-step workflows.

* currentEntry

  NavigationHistoryEntry

  required

  Returns a `NavigationHistoryEntry` object representing the location the user is currently navigated to. Use to access current URL, navigation state, or implement navigation-aware functionality based on the current location.

* navigate

  (url: string, options?: NavigationNavigateOptions) => Promise\<void>

  required

  Navigates to a specific URL, updating any provided state in the history entries list. Returns a promise that resolves when navigation is complete. Use for programmatic navigation between screens, implementing custom navigation controls, or deep-linking to specific modal states.

### NavigationHistoryEntry

Represents a single entry in the navigation history stack. Contains the URL and unique identifier for tracking navigation state and implementing history-based navigation.

* getState

  Returns a clone of the available state associated with this history entry. Use to retrieve navigation state data that was passed during navigation or to implement state-based navigation logic.

  ```ts
  () => unknown
  ```

* key

  A unique, UA-generated value that represents the history entry's slot in the entries list rather than the entry itself. Use for tracking navigation history or implementing navigation-based logic.

  ```ts
  string
  ```

* url

  The URL of this history entry. Returns \`null\` if no URL is associated with the entry. Use for URL-based navigation logic, deep-linking, or displaying current location information.

  ```ts
  string | null
  ```

```ts
export interface NavigationHistoryEntry {
  /**
   * A unique, UA-generated value that represents the history entry's slot in the entries list rather than the entry itself. Use for tracking navigation history or implementing navigation-based logic.
   */
  key: string;
  /**
   * The URL of this history entry. Returns `null` if no URL is associated with the entry. Use for URL-based navigation logic, deep-linking, or displaying current location information.
   */
  url: string | null;
  /**
   * Returns a clone of the available state associated with this history entry. Use to retrieve navigation state data that was passed during navigation or to implement state-based navigation logic.
   */
  getState(): unknown;
}
```

### NavigationNavigateOptions

Specifies configuration options for navigation operations. Allows passing state data that persists across navigation transitions.

* state

  Developer-defined information to be stored in the associated \`NavigationHistoryEntry\` once the navigation is complete, retrievable using \`getState()\`. Use to pass data between navigation states or implement stateful navigation workflows.

  ```ts
  unknown
  ```

```ts
export interface NavigationNavigateOptions {
  /**
   * Developer-defined information to be stored in the associated `NavigationHistoryEntry` once the navigation is complete, retrievable using `getState()`. Use to pass data between navigation states or implement stateful navigation workflows.
   */
  state?: unknown;
}
```

## Window

The global `window` object provides control over the extension screen lifecycle. Access these properties and methods directly through the global `window` object to manage the modal interface.

* close

  () => void

  required

  Closes the extension screen and dismisses the modal interface. Use to programmatically close the modal after completing a workflow, canceling an operation, or when user action is no longer required. This provides the same behavior as the user dismissing the modal through the UI.

## Best practices

* **Use URL-based navigation:** Implement URL-based navigation patterns that allow for deep-linking, bookmarking, and intuitive browser-like navigation within your modal workflows.
* **Manage navigation state effectively:** Use the `state` parameter in navigation options to pass data between screens, maintaining workflow context and user progress across navigation changes.

## Limitations

* The Navigation API is only available in action (modal) targets and can't be used in action (menu item), block, or tile targets that don't support multi-screen navigation.
* Navigation state is limited to serializable data and can't contain functions, complex objects, or circular references.

## Examples

Learn how to navigate between screens and manage navigation state within modal interfaces.

### Examples

* #### Navigate between multiple screens

  ##### Description

  Create multi-screen workflows within your extension using web-standard navigation. This example demonstrates using \`navigation.navigate()\` to move between different screens in your modal interface. This enables complex multi-step processes with proper navigation history management.

  ##### jsx

  ```jsx
  import { render } from "preact";

  export default async () => {
    render(<Extension />, document.body);
  };

  const Extension = () => {
    const url = navigation.currentEntry.url;

    if (url?.includes("ScreenTwo")) {
      return (
        <s-page heading="Screen Two Title">
          <s-scroll-box>
            <s-button onClick={() => navigation.navigate("ScreenOne")}>
              Navigate to Screen One
            </s-button>
            <s-button onClick={() => navigation.back()}>Go back</s-button>
          </s-scroll-box>
        </s-page>
      );
    }

    return (
      <s-page heading="Screen One Title">
        <s-scroll-box>
          <s-button onClick={() => navigation.navigate("ScreenTwo")}>
            Navigate to Screen Two
          </s-button>
          <s-button onClick={() => navigation.back()}>Go back</s-button>
        </s-scroll-box>
      </s-page>
    );
  };
  ```

* #### Navigate to a native POS screen

  ##### Description

  Navigate to native POS screens from your extension using deep link URIs. This example shows how to use \`navigation.navigate()\` with POS screen URIs to transition to core POS functionality like cart, product details, or order screens. This enables direct transitions between your extension and native POS features.

  ##### jsx

  ```jsx
  import {render} from 'preact';

  export default async () => {
    render(<Extension />, document.body);
  };

  function Extension() {
    /**
     * Available POS native screen uris:
     * - `shopify:point-of-sale/products/123` to present product details.
     * - `shopify:point-of-sale/products/123/variants/456` to present product variant details.
     * - `shopify:point-of-sale/customers/123` to present customer details.
     * - `shopify:point-of-sale/orders/123` to present order details.
     * - `shopify:point-of-sale/draft_orders/123` to present draft order details.
     * - `shopify:point-of-sale/staff/123` to present staff details.
     */
    const uri = `shopify:point-of-sale/products/${shopify.product.id}`;
    return (
      <s-page heading="POS native screen navigation">
        <s-scroll-box>
          <s-button
            onClick={() => {
              navigation.navigate(uri).catch(() => {
                // Due to staff permissions or POS subscription plan permission or invalid url, etc.
                shopify.toast.show('Unable to view product details.');
              });
            }}
          >
            View product details
          </s-button>
        </s-scroll-box>
      </s-page>
    );
  }
  ```

* #### Pass state parameters between screens

  ##### Description

  Share data between screens using navigation state parameters. This example demonstrates using the \`state\` option in \`navigation.navigate()\` to pass data when navigating. This enables screens to receive context and maintain workflow continuity across navigation transitions.

  ##### jsx

  ```jsx
  import { render } from "preact";

  export default async () => {
    render(<Extension />, document.body);
  };

  const Extension = () => {
    const url = navigation.currentEntry.url;
    
    /** @type {{ firstParam?: string; secondParam?: string }} */
    const state = navigation.currentEntry.getState();

    if (url?.includes("ScreenTwo")) {
      return (
        <s-page heading="Screen Two Title">
          <s-scroll-box>
            <s-text>First Param: {state.firstParam}</s-text>
            <s-text>Second Param: {state.secondParam}</s-text>
          </s-scroll-box>
        </s-page>
      );
    }

    return (
      <s-page heading="Screen One Title">
        <s-scroll-box>
          <s-button onClick={() => navigation.navigate("ScreenTwo", { state: { firstParam: "test", secondParam: "test2" } })}>
            Navigate to Screen Two
          </s-button>
          <s-button onClick={() => navigation.back()}>Go back</s-button>
        </s-scroll-box>
      </s-page>
    );
  };
  ```