Navigation APIAPIs
APIs
The Navigation API enables POS UI extension to navigate between screens.
Supporting targets
- () => voidrequired
The back() method of the Navigation interface navigates to the previous entry in the history list.
- NavigationHistoryEntryrequired
The currentEntry read-only property of the Navigation interface returns a NavigationHistoryEntry object representing the location the user is currently navigated to right now.
- (url: string, options?: NavigationNavigateOptions) => Promise<void>required
The navigate() method navigates to a specific URL, updating any provided state in the history entries list.
NavigationHistoryEntry
The NavigationHistoryEntry interface of the Navigation API represents a single navigation history entry.
- getState
Returns a clone of the available state associated with this history entry.
() => unknown - key
Returns the key of the history entry. This is a unique, UA-generated value that represents the history entry's slot in the entries list rather than the entry itself.
string - url
Returns the URL of this history entry.
string | null
export interface NavigationHistoryEntry {
/** Returns the key of the history entry. This is a unique, UA-generated value that represents the history entry's slot in the entries list rather than the entry itself. */
key: string;
/**
* Returns the URL of this history entry.
*/
url: string | null;
/**
* Returns a clone of the available state associated with this history entry.
*/
getState(): unknown;
}NavigationNavigateOptions
- state
Developer-defined information to be stored in the associated NavigationHistoryEntry once the navigation is complete, retrievable via getState().
unknown
export interface NavigationNavigateOptions {
/**
* Developer-defined information to be stored in the associated NavigationHistoryEntry once the navigation is complete, retrievable via getState().
*/
state?: unknown;
}Was this section helpful?
Anchor to examplesExamples
Examples of using the Navigation API
Was this section helpful?
Navigate between two screens
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 two screens
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 POS native screen with uri
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> ); }Navigate to a screen with state parameters
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> ); };