Choose a version:

Navigation
API

The API provided to extensions to navigate to extensions or host page.

Anchor to navigationNavigation

Navigation API for all extensions. Refer to supported protocols

Anchor to addEventListener addEventListener (type: "currententrychange", cb: (event: ) => void) => void required
Anchor to currentEntry currentEntry required: The currentEntry read-only property of the Navigation interface returns a NavigationHistoryEntry object representing the location the user is currently navigated to right now.
Anchor to navigate navigate required: The navigate() method navigates to a specific URL, updating any provided state in the history entries list.
Anchor to removeEventListener removeEventListener (type: "currententrychange", cb: (event: ) => void) => void required
Anchor to updateCurrentEntry updateCurrentEntry (options: ) => void required: The updateCurrentEntry() method of the Navigation interface updates the state of the currentEntry; used in cases where the state change will be independent of a navigation or reload.

Navigation

addEventListener

(type: "currententrychange", cb: (event: NavigationCurrentEntryChangeEvent) => void) => void

currentEntry
The currentEntry read-only property of the Navigation interface returns a NavigationHistoryEntry object representing the location the user is currently navigated to right now.
```
NavigationHistoryEntry
```
navigate
The navigate() method navigates to a specific URL, updating any provided state in the history entries list.
```
NavigateFunction
```

removeEventListener

(type: "currententrychange", cb: (event: NavigationCurrentEntryChangeEvent) => void) => void

updateCurrentEntry
The updateCurrentEntry() method of the Navigation interface updates the state of the currentEntry; used in cases where the state change will be independent of a navigation or reload.
```
(options: NavigationUpdateCurrentEntryOptions) => void
```

export interface Navigation {
  /**
   * The navigate() method navigates to a specific URL, updating any provided state in the history entries list.
   */
  navigate: NavigateFunction;
  /**
   * The currentEntry read-only property of the Navigation interface returns a NavigationHistoryEntry object representing the location the user is currently navigated to right now.
   */
  currentEntry: NavigationHistoryEntry;
  /**
   * The updateCurrentEntry() method of the Navigation interface updates the state of the currentEntry; used in cases where the state change will be independent of a navigation or reload.
   */
  updateCurrentEntry(options: NavigationUpdateCurrentEntryOptions): void;
  addEventListener(
    type: 'currententrychange',
    cb: (event: NavigationCurrentEntryChangeEvent) => void,
  ): void;
  removeEventListener(
    type: 'currententrychange',
    cb: (event: NavigationCurrentEntryChangeEvent) => void,
  ): void;
}

NavigationCurrentEntryChangeEvent

The NavigationCurrentEntryChangeEvent interface of the Navigation API is the event object for the currententrychange event, which fires when the Navigation.currentEntry has changed.

from
Returns the NavigationHistoryEntry that was navigated from.
```
NavigationHistoryEntry
```
navigationType
Returns the type of the navigation that resulted in the change.
```
NavigationTypeString
```

export interface NavigationCurrentEntryChangeEvent {
  /**
   * Returns the type of the navigation that resulted in the change.
   */
  navigationType?: NavigationTypeString;
  /**
   * Returns the NavigationHistoryEntry that was navigated from.
   */
  from: NavigationHistoryEntry;
}

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

NavigationTypeString

An enumerated value representing the type of navigation.

'push' | 'replace' | 'traverse'

NavigateFunction

export interface NavigateFunction {
  /**
   * Navigates to a specific URL, updating any provided state in the history entries list.
   * @param url The destination URL to navigate to.
   */
  (url: string, options?: NavigationNavigateOptions): void;
}

NavigationUpdateCurrentEntryOptions

state
```
unknown
```

export interface NavigationUpdateCurrentEntryOptions {
  state: unknown;
}

Was this section helpful?

Navigation example

Preact

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

export default async () => {

render(<Extension />, document.body);

};

function Extension() {

return (

<s-button

onClick={() => {

navigation.navigate('extension://orders');

}}

Navigate to orders path

</s-button>

);

}

examples

Navigation example

Preact

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

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

function Extension() {
  return (
    <s-button
      onClick={() => {
        navigation.navigate('extension://orders');
      }}
    >
      Navigate to orders path
    </s-button>
  );
}

NavigationAPI

Anchor to navigationNavigation

Navigation

NavigationCurrentEntryChangeEvent

NavigationHistoryEntry

NavigationTypeString

NavigateFunction

NavigationUpdateCurrentEntryOptions

examples

Navigation example

Preact

Navigation
API