Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Choose a version:

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.

Anchor to Use casesUse cases

Multi-screen workflows: Build multi-screen modal workflows with navigation and parameter passing.
Wizard interfaces: Implement wizard-style interfaces guiding users through sequential steps.
Hierarchical navigation: Create hierarchical navigation with push/pop patterns.
Modal dismissal: Handle modal dismissal programmatically when workflows complete.

Support

Targets (9)

Supported targets

Anchor to PropertiesProperties

The Navigation API object provides screen-based navigation functionality for POS UI extensions. Access the following properties on the API object to navigate between screens, manage navigation stacks, and dismiss modal interfaces.

Anchor to dismiss 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.
Anchor to navigate 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.
Anchor to pop 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.

Examples

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 (

<Button

title="Navigate to Screen Two"

onPress={() => api.navigation.navigate('ScreenTwo')}

</Screen>

<Button

title="Navigate to Screen One"

onPress={() => api.navigation.navigate('ScreenOne')}

</Screen>

</Navigator>

);

};

export default reactExtension('pos.home.modal.render', () => (

));

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

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

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

// 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

// 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);

Anchor to Best practicesBest 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.

Anchor to LimitationsLimitations

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.

Was this page helpful?