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 windowWindow
- Anchor to closeclose() => voidrequired
The close() method of the window interface closes the extension screen.
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> ); };