---
title: Navigator
description: >-
The Navigator component manages navigation between multiple Screen components
within a POS UI extension. Use it to create multi-screen workflows with proper
navigation stack management and initial screen configuration.
Navigator works with the Navigation API to provide complete navigation control
for complex POS workflows that require multiple views and user interactions.
Navigator components maintain navigation history across app lifecycle events
and supports deep linking to specific screens, enabling merchants to return to
their exact workflow state after interruptions The component supports
gesture-based navigation like swipe-to-go-back on platforms where this is
standard, providing familiar interaction patterns that feel native to each
platform.
api_version: 2024-10
api_name: pos-ui-extensions
source_url:
html: >-
https://shopify.dev/docs/api/pos-ui-extensions/2024-10/ui-components/navigation-and-content/navigator
md: >-
https://shopify.dev/docs/api/pos-ui-extensions/2024-10/ui-components/navigation-and-content/navigator.md
---
# Navigator
The Navigator component manages navigation between multiple Screen components within a POS UI extension. Use it to create multi-screen workflows with proper navigation stack management and initial screen configuration.
Navigator works with the Navigation API to provide complete navigation control for complex POS workflows that require multiple views and user interactions.
Navigator components maintain navigation history across app lifecycle events and supports deep linking to specific screens, enabling merchants to return to their exact workflow state after interruptions The component supports gesture-based navigation like swipe-to-go-back on platforms where this is standard, providing familiar interaction patterns that feel native to each platform.
### Support Targets (6)
### Supported targets
* [pos.customer-details.action.render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/customer-details#customer-details-action-modal-)
* [pos.draft-order-details.action.render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/draft-order-details#draft-order-details-action-modal-)
* [pos.home.modal.render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/home-screen#home-screen-action-modal-)
* [pos.order-details.action.render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/order-details#order-details-action-modal-)
* [pos.product-details.action.render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/product-details#product-details-action-modal-)
* [pos.purchase.post.action.render](https://shopify.dev/docs/api/pos-ui-extensions/2024-10/targets/post-purchase#post-purchase-action-modal-)
#### Use cases
* **Multi-step workflows:** Create workflows like customer onboarding or product configuration.
* **Settings interfaces:** Build configuration interfaces with separate screens for different categories.
* **Screen lifecycle:** Provide structured navigation with proper back button handling.
* **Parameter passing:** Support deep-linking or parameter passing between screens.
## Examples
### Navigate between screens
Create a multi-screen navigation flow within your extension. This example shows how to set up a Navigator with multiple Screen components and navigate between them, enabling complex workflows, wizards, or detailed views with proper navigation stack management.
## Navigate between screens
### Pass data between screens
Navigate to screens while passing data as parameters. This example demonstrates how to send information from one screen to another using navigation parameters, enabling contextual data flow through multi-step workflows.
### Present a screen as a sheet
Show a screen using sheet presentation style for modal-like interactions. This example demonstrates how to present screens as overlays that slide up from the bottom, useful for quick actions or secondary information without losing the parent screen context.
### Examples
* #### Navigate between screens
##### Description
Create a multi-screen navigation flow within your extension. This example shows how to set up a Navigator with multiple Screen components and navigate between them, enabling complex workflows, wizards, or detailed views with proper navigation stack management.
##### React
```tsx
import React from 'react'
import { Screen, Text, Navigator, reactExtension, Button, useApi } from '@shopify/ui-extensions-react/point-of-sale';
const Modal = () => {
const api = useApi<'pos.home.modal.render'>();
return (
Home screenDetails screen
)
}
export default reactExtension('pos.home.modal.render', () => );
```
##### TS
```ts
import {
extension,
Screen,
Navigator,
Text,
Button,
} from '@shopify/ui-extensions/point-of-sale';
export default extension('pos.home.modal.render', (root, api) => {
const homeScreen = root.createComponent(Screen, {
name: 'Home',
title: 'Home',
});
const homeText = root.createComponent(Text);
homeText.append('Home screen');
homeScreen.append(homeText);
const navigateButton = root.createComponent(Button, {
title: 'Navigate to details',
onPress: () => api.navigation.navigate('Details'),
});
homeScreen.append(navigateButton);
const detailsScreen = root.createComponent(Screen, {
name: 'Details',
title: 'Details',
});
const detailsText = root.createComponent(Text);
detailsText.append('Details screen');
detailsScreen.append(detailsText);
const navigator = root.createComponent(Navigator);
navigator.append(homeScreen);
navigator.append(detailsScreen);
root.append(navigator);
});
```
* #### Pass data between screens
##### Description
Navigate to screens while passing data as parameters. This example demonstrates how to send information from one screen to another using navigation parameters, enabling contextual data flow through multi-step workflows.
##### React
```tsx
import React, {useState} from 'react';
import {
Screen,
Text,
Navigator,
reactExtension,
Button,
useApi,
} from '@shopify/ui-extensions-react/point-of-sale';
const Modal = () => {
return (
);
};
const HomeScreen = () => {
const api = useApi<'pos.home.modal.render'>();
return (
Home screen
);
};
const DetailsScreen = () => {
const [params, setParams] = useState();
return (
{`Order ID: ${params.orderId}`}
);
};
export default reactExtension('pos.home.modal.render', () => );
```
##### TS
```ts
import {
extension,
Screen,
Navigator,
Text,
Button,
} from '@shopify/ui-extensions/point-of-sale';
export default extension('pos.home.modal.render', (root, api) => {
const homeScreen = root.createComponent(Screen, {
name: 'Home',
title: 'Home',
});
const homeText = root.createComponent(Text);
homeText.append('Home screen');
homeScreen.append(homeText);
const navigateButton = root.createComponent(Button, {
title: 'Navigate to details',
onPress: () => api.navigation.navigate('Details', {orderId: '123'}),
});
homeScreen.append(navigateButton);
const detailsText = root.createComponent(Text);
const detailsScreen = root.createComponent(Screen, {
name: 'Details',
title: 'Details',
onReceiveParams: (params) => {
detailsText.replaceChildren(`Order ID: ${params.orderId}`);
},
});
detailsScreen.append(detailsText);
const navigator = root.createComponent(Navigator);
navigator.append(homeScreen);
navigator.append(detailsScreen);
root.append(navigator);
});
```
* #### Present a screen as a sheet
##### Description
Show a screen using sheet presentation style for modal-like interactions. This example demonstrates how to present screens as overlays that slide up from the bottom, useful for quick actions or secondary information without losing the parent screen context.
##### React
```tsx
import React from 'react'
import { Screen, Text, Navigator, reactExtension, Button, useApi } from '@shopify/ui-extensions-react/point-of-sale';
const Modal = () => {
const api = useApi<'pos.home.modal.render'>();
return (
Home screenDetails screen
)
}
export default reactExtension('pos.home.modal.render', () => );
```
##### TS
```ts
import {
extension,
Screen,
Navigator,
Text,
Button,
} from '@shopify/ui-extensions/point-of-sale';
export default extension('pos.home.modal.render', (root, api) => {
const homeScreen = root.createComponent(Screen, {
name: 'Home',
title: 'Home',
});
const homeText = root.createComponent(Text);
homeText.append('Home screen');
homeScreen.append(homeText);
const navigateButton = root.createComponent(Button, {
title: 'Navigate to details',
onPress: () => api.navigation.navigate('Details'),
});
homeScreen.append(navigateButton);
const detailsScreen = root.createComponent(Screen, {
name: 'Details',
title: 'Details',
presentation: {sheet: true},
});
const detailsText = root.createComponent(Text);
detailsText.append('Details screen');
detailsScreen.append(detailsText);
const navigator = root.createComponent(Navigator);
navigator.append(homeScreen);
navigator.append(detailsScreen);
root.append(navigator);
});
```
## Properties
Configure the following properties on the Navigator component.
* **initialScreenName**
**string**
The name of the initial Screen component to display when the Navigator is first rendered. Must match the `name` property of a child Screen component.
## Best practices
* **Use descriptive screen names for navigation:** Choose clear, unique screen names that accurately represent their content and purpose. These names are used by the Navigation API for programmatic navigation and should be meaningful for code maintainability.
* **Set appropriate initial screens:** Select initial screens that provide the most logical entry point for your workflow. Consider the context in which your extension will be launched and what users will most likely want to see first.
* **Implement proper navigation patterns:** Use the Navigation API methods consistently—`navigate()` for moving forward, `pop()` for going back, and `dismiss()` for closing the extension. This creates predictable navigation behavior that users can understand.
* **Handle screen parameters effectively:** When passing parameters between screens using `navigation.navigate()`, ensure receiving screens properly handle the data through their `onReceiveParams` callbacks. Design parameter structures that are maintainable and type-safe.
* **Consider navigation context and user flow:** Design navigation patterns that make sense within the broader POS workflow. Avoid deep navigation hierarchies that might confuse users or disrupt their primary tasks.
## Limitations
* Navigator requires Screen components as children—it can't manage navigation for other component types or standalone content.
* Navigation state is managed internally—external navigation state management or complex routing patterns require custom implementation using the Navigation API.
* The component is designed for modal-style navigation within POS UI extensions—it's not suitable for main application navigation or replacing core POS navigation patterns.