---
title: Navigation
description: The API provided to extensions to navigate to extensions or host page.
api_version: 2025-10
api_name: customer-account-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/latest/apis/navigation
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/latest/apis/navigation.md
---

# Navigation

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

## Navigation

Navigation API for all extensions. [Refer to supported protocols](https://shopify.dev/docs/api/customer-account-ui-extensions/unstable#custom-protocols)

* addEventListener

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

  required

* currentEntry

  NavigationHistoryEntry

  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.

* navigate

  NavigateFunction

  required

  The navigate() method navigates to a specific URL, updating any provided state in the history entries list.

* removeEventListener

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

  required

* updateCurrentEntry

  (options: NavigationUpdateCurrentEntryOptions) => 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.

### 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.

  ```ts
  NavigationHistoryEntry
  ```

* navigationType

  Returns the type of the navigation that resulted in the change.

  ```ts
  NavigationTypeString
  ```

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

  ```ts
  () => 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.

  ```ts
  string
  ```

* url

  Returns the URL of this history entry.

  ```ts
  string | null
  ```

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

```ts
'push' | 'replace' | 'traverse'
```

### NavigateFunction



```ts
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

  ```ts
  unknown
  ```

```ts
export interface NavigationUpdateCurrentEntryOptions {
  state: unknown;
}
```

### Examples

* #### Extension.jsx

  ##### Default

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