Choose a version:

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.

Use cases

Multi-screen workflows: Implement workflows with URL-based navigation and browser history support.
Wizard interfaces: Build wizard-style interfaces allowing forward and backward navigation.
Deep linking: Create deep-linkable modal states that can be bookmarked or shared.
Navigation events: Handle navigation events to save progress or trigger cleanup.

Anchor to navigationapiNavigationApi

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.

Anchor to back 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.
Anchor to currentEntry currentEntry 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.
Anchor to navigate navigate (url: string, options?: ) => 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.
```
() => 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.
```
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.
```
string | null
```

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

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;
}

Anchor to windowWindow

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.

Anchor to close 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.

Examples

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>

);

};

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

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

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

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>
  );
};

Anchor to best-practicesBest 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.

Anchor to limitationsLimitations

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.

Was this page helpful?