---
title: Navigation API
description: >-
  The Navigation API provides screen-based navigation functionality for POS UI
  extensions, allowing you to navigate between screens, manage navigation
  stacks, and dismiss modal interfaces within full-screen modal workflows. The
  API enables multi-screen experiences with parameter passing and navigation
  control.
api_version: 2025-04
api_name: pos-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/pos-ui-extensions/2025-04/target-apis/platform-apis/navigation-api
  md: >-
    https://shopify.dev/docs/api/pos-ui-extensions/2025-04/target-apis/platform-apis/navigation-api.md
---

# Navigation API

The Navigation API provides screen-based navigation functionality for POS UI extensions, allowing you to navigate between screens, manage navigation stacks, and dismiss modal interfaces within full-screen modal workflows. The API enables multi-screen experiences with parameter passing and navigation control.

## NavigationApi

The global `navigation` object provides web-standard navigation functionality. Access these properties and methods directly through the global `navigation` object to manage navigation within modal interfaces.

* dismiss

  () => void

  required

  Dismisses the extension modal completely. Use for closing the modal when workflows are complete, cancelled, or when users need to return to the main POS interface.

* navigate

  (screenName: string, params?: any) => void

  required

  Navigate to a route in current navigation tree. Pushes the specified screen if it isn't present in the navigation tree, goes back to a created screen otherwise. Use for implementing multi-screen workflows with parameter passing between screens.

* pop

  () => void

  required

  Pops the currently shown screen from the navigation stack. Use for implementing back navigation, returning to previous screens, or programmatically navigating backward in multi-screen workflows.

## Best practices

* **Handle navigation parameters effectively:** Use navigation parameters to pass data between screens, maintaining workflow context and user progress across screen transitions.
* **Implement proper screen management:** Design screens that can be pushed and popped.
* **Provide clear navigation controls:** Implement clear navigation controls and feedback so users understand their current location in the workflow and how to navigate between screens.

## Limitations

* The Navigation API is only available in action (modal) targets and can't be used in action (menu item), block, or tile targets that don't support multi-screen navigation.
* Screen navigation is based on screen names and the navigation stack, which differs from URL-based navigation patterns found in web applications.
* Navigation parameters must be serializable and can't contain functions, complex objects, or circular references.

## Examples

Learn how to navigate between screens, manage navigation stacks, and control multi-screen modal experiences.

### Examples

* #### Create a multi-screen modal

  ##### Description

  Create a navigation flow with multiple screens in a modal interface. This example shows how to set up a Navigator with two screens and navigate between them, enabling multi-step workflows, wizards, or detailed views within your extension.

  ##### React

  ```tsx
  import React from 'react';
  import {
    reactExtension,
    useApi,
    Navigator,
    Screen,
    Button,
  } from '@shopify/ui-extensions-react/point-of-sale';

  const SmartGridModal = () => {
    const api = useApi<'pos.home.modal.render'>();

    return (
      <Navigator>
        <Screen name="ScreenOne" title="Screen One Title">
          <Button
            title="Navigate to Screen Two"
            onPress={() => api.navigation.navigate('ScreenTwo')}
          />
        </Screen>
        <Screen name="ScreenTwo" title="Screen Two Title">
          <Button
            title="Navigate to Screen One"
            onPress={() => api.navigation.navigate('ScreenOne')}
          />
        </Screen>
      </Navigator>
    );
  };

  export default reactExtension('pos.home.modal.render', () => (
    <SmartGridModal />
  ));
  ```

  ##### TS

  ```ts
  import {
    extension,
    Button,
    Navigator,
    Screen,
  } from '@shopify/ui-extensions/point-of-sale';

  export default extension('pos.home.modal.render', (root, api) => {
    let navigator = root.createComponent(Navigator);

    let screenOne = root.createComponent(Screen, {
      name: 'ScreenOne',
      title: 'Screen One Title',
    });

    let screenTwo = root.createComponent(Screen, {
      name: 'ScreenTwo',
      title: 'Screen Two Title',
    });

    let navigateScreenOneBtn = root.createComponent(Button, {
      title: 'Navigate to Screen One',
      onPress: () => api.navigation.navigate('ScreenOne'),
    });

    let navigateScreenTwoBtn = root.createComponent(Button, {
      title: 'Navigate to Screen Two',
      onPress: () => api.navigation.navigate('ScreenTwo'),
    });

    screenOne.appendChild(navigateScreenTwoBtn);
    screenTwo.appendChild(navigateScreenOneBtn);
    navigator.appendChild(screenOne);
    navigator.appendChild(screenTwo);
    root.appendChild(navigator);
  });
  ```

* #### Navigate to another screen

  ##### Description

  Navigate programmatically to a specific screen in your navigation hierarchy. This example demonstrates using the global \`navigation\` object to push a new screen onto the navigation stack. Note that the target screen must already be defined in your Navigator component before you can navigate to it.

  ##### React

  ```tsx
  // You can navigate to any of these three screens since they all exist within the same Navigator.
  return (
    <Navigator>
      <Screen name="ScreenOne" title="Screen One Title" />
      <Screen name="ScreenTwo" title="Screen Two  Title" />
      <Screen name="ScreenThree" title="Screen Three Title" />
    </Navigator>
  );
  ```

  ##### TS

  ```ts
  // You can navigate to any of these three screens since they all exist within the same Navigator.
  let navigator = root.createComponent(Navigator);

  let screenOne = root.createComponent(Screen, {
    name: 'ScreenOne',
    title: 'Screen One Title',
  });

  let screenTwo = root.createComponent(Screen, {
    name: 'ScreenTwo',
    title: 'Screen Two Title',
  });

  let screenThree = root.createComponent(Screen, {
    name: 'ScreenThree',
    title: 'Screen Three Title',
  });

  navigator.appendChild(screenOne);
  navigator.appendChild(screenTwo);
  navigator.appendChild(screenThree);
  root.appendChild(navigator);
  ```