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

# NavigationAPI

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/2025-07#custom-protocols)

* navigate

  NavigateFunction

  required

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

### 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?: NavigationOptions): void;
}
```

## Full-Page Navigation

Only available for full-page extension `customer-account.page.render`

* 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: { state: Record\<string, any>; }) => 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
  NavigationType
  ```

```ts
export interface NavigationCurrentEntryChangeEvent {
  /**
   * Returns the type of the navigation that resulted in the change.
   */
  navigationType: NavigationType;
  /**
   * 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
  () => Record<string, any>
  ```

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

```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;
  /**
   * Returns a clone of the available state associated with this history entry.
   */
  getState(): Record<string, any>;
}
```

### NavigationType

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?: NavigationOptions): void;
}
```

## use​Navigation​Current​Entry()

Returns the live navigation current entry

### Returns

* NavigationHistoryEntry

  ### NavigationHistoryEntry

  * getState

    () => Record\<string, any>

    Returns a clone of the available state associated with this history entry.

  * key

    string

    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.

  * url

    string

    Returns the URL of this history entry.

### 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
  () => Record<string, any>
  ```

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

```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;
  /**
   * Returns a clone of the available state associated with this history entry.
   */
  getState(): Record<string, any>;
}
```

### Examples

* #### Navigation example

  ##### React

  ```React
  import {
    reactExtension,
    useApi,
    Button,
  } from '@shopify/ui-extensions-react/customer-account';

  export default reactExtension(
    'customer-account.page.render',
    () => <App />,
  );

  function App() {
    const {navigation} = useApi();

    return (
      <Button
        onPress={() => {
          navigation.navigate('extension://orders');
        }}
      >
        Navigate to orders path
      </Button>
    );
  }
  ```

  ##### js

  ```js
  import {
    extend,
    Button,
  } from '@shopify/customer-account-ui-extensions';

  export default extend(
    'customer-account.page.render',
    (root, {navigation}) => {
      const button = root.createComponent(
        Button,
        {
          onPress: () => {
            navigation.navigate(
              'extension://orders',
            );
          },
        },
        'Navigate to orders path',
      );
      root.appendChild(button);
    },
  );
  ```

## Examples

Navigation api examples

Listening for navigation current entry events

Using the live current entry value in a full-page extension

Navigating to customer account native order index page

### Examples

* #### Listening for navigation current entry events

  ##### React

  ```jsx
  import React, {
    useEffect,
    useState,
    useCallback,
  } from 'react';
  import {
    reactExtension,
    useApi,
    BlockStack,
    Heading,
    Image,
    ResourceItem,
    Text,
  } from '@shopify/ui-extensions-react/customer-account';
  import type {NavigationCurrentEntryChangeEvent} from '@shopify/ui-extensions/customer-account';

  export default reactExtension(
    'customer-account.page.render',
    () => <App />,
  );

  function App() {
    const {navigation} = useApi();

    const [currentEntryState, setCurrentEntry] =
      useState<NavigationCurrentEntryChangeEvent>();

    const updateCurrentEntryState = useCallback(
      (
        event: NavigationCurrentEntryChangeEvent,
      ) => {
        setCurrentEntry(event);
      },
      [],
    );
    useEffect(() => {
      navigation.addEventListener(
        'currententrychange',
        updateCurrentEntryState,
      );

      return () => {
        navigation.removeEventListener(
          'currententrychange',
          updateCurrentEntryState,
        );
      };
    }, [updateCurrentEntryState, navigation]);

    function getWishlistId(_url: string): string {
      throw new Error('Function not implemented.');
    }

    const wishlistIdPattern =
      /^extension:\/wishlists\/(\d+)$/;
    const wishlistDetailsMatch =
      navigation.currentEntry.url.match(
        wishlistIdPattern,
      );

    if (
      navigation.currentEntry.url === 'extension:/'
    ) {
      return <Wishlists />;
    } else if (wishlistDetailsMatch) {
      return (
        <WishlistDetails
          id={getWishlistId(
            wishlistDetailsMatch[1],
          )}
        />
      );
    } else {
      return <NotFound />;
    }
  }

  interface WishlistDetailsProps {
    id: string;
  }

  interface Wishlist {
    id: string;
    items: {
      productId: string;
      productLink: string;
      productImage: string;
      label: string;
    }[];
  }

  function Wishlists() {
    const [wishlists, setWishlists] =
      useState<Wishlist[]>();

    const [loading, setLoading] = useState(true);

    useEffect(() => {
      async function fetchWishlists() {
        setLoading(true);
        const response = await fetch(
          `https://your-backend.com/api/wishlists`,
        );
        const wishlists = await response.json();
        setLoading(false);
        setWishlists(wishlists);
      }

      void fetchWishlists();
    }, []);

    if (loading) {
      return <Text>Loading...</Text>;
    }

    if (!wishlists) {
      return <NotFound />;
    }

    return (
      <BlockStack>
        {wishlists.map((item) => {
          return (
            <ResourceItem
              to={`/wishlist/${item.id}`}
              key={item.id}
            >
              <BlockStack>
                <Image
                  source={
                    item.items[0].productImage
                  }
                />
                <Text>{item.items[0].label}</Text>
              </BlockStack>
            </ResourceItem>
          );
        })}
      </BlockStack>
    );
  }

  function WishlistDetails({
    id,
  }: WishlistDetailsProps) {
    const [wishlist, setWishlist] =
      useState<Wishlist>();

    const [loading, setLoading] = useState(true);

    useEffect(() => {
      async function fetchWishlist() {
        setLoading(true);
        const response = await fetch(
          `https://your-backend.com/api/wishlists/${id}`,
        );
        const wishlist = await response.json();
        setLoading(false);
        setWishlist(wishlist);
      }

      void fetchWishlist();
    }, [id]);

    if (loading) {
      return <Text>Loading...</Text>;
    }

    if (!wishlist) {
      return <NotFound />;
    }

    return (
      <BlockStack>
        {wishlist.items.map((item) => {
          return (
            <ResourceItem
              to={`/wishlist/${id}/${item.productId}`}
              key={item.productId}
            >
              <BlockStack>
                <Image source={item.productImage} />
                <Text>{item.label}</Text>
              </BlockStack>
            </ResourceItem>
          );
        })}
      </BlockStack>
    );
  }

  function NotFound() {
    return (
      <BlockStack>
        <Heading>Resource Not found</Heading>
      </BlockStack>
    );
  }
  ```

* #### Using the live current entry value in a full-page extension

  ##### React

  ```jsx
  import React, {
    useEffect,
    useState,
  } from 'react';
  import {
    reactExtension,
    BlockStack,
    Heading,
    Image,
    ResourceItem,
    Text,
    useNavigationCurrentEntry,
  } from '@shopify/ui-extensions-react/customer-account';
  import type {NavigationCurrentEntryChangeEvent} from '@shopify/ui-extensions/customer-account';

  export default reactExtension(
    'customer-account.page.render',
    () => <App />,
  );

  function App() {
    const currentEntry = useNavigationCurrentEntry();

    function getWishlistId(_url: string): string {
      throw new Error('Function not implemented.');
    }

    const wishlistIdPattern =
      /^extension:\/wishlists\/(\d+)$/;
    const wishlistDetailsMatch =
      currentEntry.url.match(
        wishlistIdPattern,
      );

    if (
      currentEntry.url === 'extension:/'
    ) {
      return <Wishlists />;
    } else if (wishlistDetailsMatch) {
      return (
        <WishlistDetails
          id={getWishlistId(
            wishlistDetailsMatch[1],
          )}
        />
      );
    } else {
      return <NotFound />;
    }
  }

  interface WishlistDetailsProps {
    id: string;
  }

  interface Wishlist {
    id: string;
    items: {
      productId: string;
      productLink: string;
      productImage: string;
      label: string;
    }[];
  }

  function Wishlists() {
    const [wishlists, setWishlists] =
      useState<Wishlist[]>();

    const [loading, setLoading] = useState(true);

    useEffect(() => {
      async function fetchWishlists() {
        setLoading(true);
        const response = await fetch(
          `https://your-backend.com/api/wishlists`,
        );
        const wishlists = await response.json();
        setLoading(false);
        setWishlists(wishlists);
      }

      void fetchWishlists();
    }, []);

    if (loading) {
      return <Text>Loading...</Text>;
    }

    if (!wishlists) {
      return <NotFound />;
    }

    return (
      <BlockStack>
        {wishlists.map((item) => {
          return (
            <ResourceItem
              to={`/wishlist/${item.id}`}
              key={item.id}
            >
              <BlockStack>
                <Image
                  source={
                    item.items[0].productImage
                  }
                />
                <Text>{item.items[0].label}</Text>
              </BlockStack>
            </ResourceItem>
          );
        })}
      </BlockStack>
    );
  }

  function WishlistDetails({
    id,
  }: WishlistDetailsProps) {
    const [wishlist, setWishlist] =
      useState<Wishlist>();

    const [loading, setLoading] = useState(true);

    useEffect(() => {
      async function fetchWishlist() {
        setLoading(true);
        const response = await fetch(
          `https://your-backend.com/api/wishlists/${id}`,
        );
        const wishlist = await response.json();
        setLoading(false);
        setWishlist(wishlist);
      }

      void fetchWishlist();
    }, [id]);

    if (loading) {
      return <Text>Loading...</Text>;
    }

    if (!wishlist) {
      return <NotFound />;
    }

    return (
      <BlockStack>
        {wishlist.items.map((item) => {
          return (
            <ResourceItem
              to={`/wishlist/${id}/${item.productId}`}
              key={item.productId}
            >
              <BlockStack>
                <Image source={item.productImage} />
                <Text>{item.label}</Text>
              </BlockStack>
            </ResourceItem>
          );
        })}
      </BlockStack>
    );
  }

  function NotFound() {
    return (
      <BlockStack>
        <Heading>Resource Not found</Heading>
      </BlockStack>
    );
  }
  ```

* #### Navigating to customer account native order index page

  ##### React

  ```jsx
  import {
    reactExtension,
    useApi,
    Page,
    Button,
  } from '@shopify/customer-account-ui-extensions-react';

  export default reactExtension(
    'customer-account.page.render',
    () => <App />,
  );

  function App() {
    const { navigation } = useApi();

    return (
      <Page
        title="Wishlist"
        secondaryAction={
          <Button
            onPress={navigation.navigate(
              'shopify:customer-account/orders',
            )}
          >
            Back to orders index
          </Button>
        }
      >
        <p>Wishlist content</p>
      </Page>
    );
  }
  ```

## Related

[APIs - StandardApi](https://shopify.dev/docs/api/customer-account-ui-extensions/apis/standardapi)