Choose a version:

Screen

The Screen component represents a screen in the navigation stack with full control over presentation, actions, and navigation lifecycle. Use it to create navigable screens with titles, loading states, and custom navigation behavior.

The component manages full-screen presentations with proper navigation stack integration, allowing extensions to push and pop screens as part of the POS navigation flow. It handles transitions, back button behavior, and safe area padding automatically, ensuring extensions provide native-feeling navigation experiences on both iOS and Android devices.

Screen components maintain scroll position across navigation operations where appropriate, allowing merchants to return to their previous location after viewing details or completing sub-tasks.

Support

Targets (2)

Supported targets

Use cases

Multi-step workflows: Create workflows with navigation between different screens.
Configuration interfaces: Build settings interfaces requiring separate screens for different categories.
Modal presentations: Implement modal-style presentations for focused tasks or data entry.
Loading states: Provide loading states during asynchronous operations.

Anchor to examplesExamples

Anchor to example-navigate-to-a-different-screenNavigate to a different screen

Implement navigation between screens using the Navigator component. This example shows how to set up basic screen navigation with a button that navigates to a details screen, enabling multi-screen workflows and user journeys within your extension.

Navigate to a different screen

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 (

<Text>Home screen</Text>

<Button title="Navigate to details" onPress={() => api.navigation.navigate('Details')} />

</Screen>

<Text>Details screen</Text>

</Screen>

</Navigator>

)

}

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

Anchor to example-pass-data-between-screens-during-navigationPass data between screens during navigation

Navigate to another screen while passing data through parameters. This example demonstrates how to pass information like IDs or values when navigating, allowing the destination screen to access and display context-specific data based on user selections.

Pass data between screens during navigation

import React, {useState} from 'react';

import {

Screen,

Text,

Navigator,

reactExtension,

Button,

useApi,

} from '@shopify/ui-extensions-react/point-of-sale';

const Modal = () => {

return (

</Navigator>

);

};

const HomeScreen = () => {

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

return (

<Text>Home screen</Text>

<Button

title="Navigate to details"

onPress={() => api.navigation.navigate('Details', {orderId: '123'})}

/>

</Screen>

);

};

const DetailsScreen = () => {

const [params, setParams] = useState<pos.home.modal.render>();

return (

<Screen

name="Details"

title="Details"

presentation={{sheet: true}}

onReceiveParams={setParams}

>

<Text>{`Order ID: ${params.orderId}`}</Text>

</Screen>

);

};

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

Anchor to example-present-a-screen-as-a-modal-sheetPresent a screen as a modal sheet

Navigate to a screen with a sheet presentation style for contextual overlays. This example shows how to use sheet presentation mode to display a screen as a modal overlay, useful for quick actions, forms, or secondary content that doesn't require full-screen navigation.

Present a screen as a modal sheet

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 (

<Text>Home screen</Text>

<Button title="Navigate to details" onPress={() => api.navigation.navigate('Details')} />

</Screen>

<Text>Details screen</Text>

</Screen>

</Navigator>

)

}

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

Examples

Navigate to a different screen

Description

Implement navigation between screens using the Navigator component. This example shows how to set up basic screen navigation with a button that navigates to a details screen, enabling multi-screen workflows and user journeys within your extension.

React

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 (
<Navigator>
<Screen name="Home" title="Home">
<Text>Home screen</Text>
<Button title="Navigate to details" onPress={() => api.navigation.navigate('Details')} />
</Screen>
<Screen name="Details" title="Details">
<Text>Details screen</Text>
</Screen>
</Navigator>
)
}

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

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 during navigation

Description

Navigate to another screen while passing data through parameters. This example demonstrates how to pass information like IDs or values when navigating, allowing the destination screen to access and display context-specific data based on user selections.

React

import React, {useState} from 'react';

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

const Modal = () => {
return (
<Navigator>
<HomeScreen />
<DetailsScreen />
</Navigator>
);
};

const HomeScreen = () => {
const api = useApi<'pos.home.modal.render'>();
return (
<Screen name="Home" title="Home">
<Text>Home screen</Text>
<Button
title="Navigate to details"
onPress={() => api.navigation.navigate('Details', {orderId: '123'})}
/>
</Screen>
);
};

const DetailsScreen = () => {
const [params, setParams] = useState<pos.home.modal.render>();

return (
<Screen
name="Details"
title="Details"
presentation={{sheet: true}}
onReceiveParams={setParams}
>
<Text>{`Order ID: ${params.orderId}`}</Text>
</Screen>
);
};

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

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 modal sheet

Description

Navigate to a screen with a sheet presentation style for contextual overlays. This example shows how to use sheet presentation mode to display a screen as a modal overlay, useful for quick actions, forms, or secondary content that doesn't require full-screen navigation.

React

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 (
<Navigator>
<Screen name="Home" title="Home">
<Text>Home screen</Text>
<Button title="Navigate to details" onPress={() => api.navigation.navigate('Details')} />
</Screen>
<Screen name="Details" title="Details" presentation={{sheet: true}}>
<Text>Details screen</Text>
</Screen>
</Navigator>
)
}

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

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

Anchor to screenScreen

Anchor to name name string required: The unique identifier used to identify this screen as a destination in the navigation stack.
Anchor to title title string required: The title text of the screen that will be displayed in the UI header.
Anchor to isLoading isLoading boolean: Displays a loading indicator when true. Set this during asynchronous tasks and return to false when data becomes available.
Anchor to presentation presentation: The presentation configuration that dictates how the screen will be displayed when navigated to.
Anchor to secondaryAction secondaryAction: The configuration for a secondary action button displayed on the screen header.
Anchor to onNavigate onNavigate () => void: A callback function triggered when the screen is navigated to in the navigation stack.
Anchor to onNavigateBack onNavigateBack () => void: A callback function triggered when the user navigates back from this screen. Runs after the screen is unmounted.
Anchor to overrideNavigateBack overrideNavigateBack () => void: A callback function that allows you to override the default back navigation action. Runs when the screen is mounted.
Anchor to onReceiveParams onReceiveParams (params: any) => void: A callback function triggered when the navigation event completes with any passed parameters. Runs when screen is mounted (with undefined).

ScreenPresentationProps

Defines the presentation options for how the screen appears when navigated to.

sheet
Displays the screen from the bottom as a sheet presentation when true during navigation. The text label displayed on the secondary action button in the screen's action bar.
```
boolean
```

export interface ScreenPresentationProps {
sheet?: boolean;
}

SecondaryActionProps

Defines the configuration options for secondary action buttons displayed in the screen header.

text
The text label displayed on the secondary action button in the screen's action bar.
```
string
```
onPress
A callback function triggered when the secondary action button is pressed by the user.
```
() => void
```
isEnabled
Whether the secondary action button can be tapped and is interactive.
```
boolean
```

export interface SecondaryActionProps {
text: string;
onPress: () => void;
isEnabled?: boolean;
}

Anchor to best-practicesBest practices

Implement proper loading states: Use the isLoading property to provide visual feedback during async operations. Set it to true when starting data fetching or processing, and false when operations complete to maintain user awareness.
Handle navigation lifecycle appropriately: Use onNavigate for screen initialization, onNavigateBack for cleanup operations, and onReceiveParams for handling passed data. Proper lifecycle management ensures smooth transitions and data consistency.
Choose appropriate presentation styles: Use sheet presentation for focused tasks, modal-style interactions, or when you want to maintain context with the previous screen. Reserve standard presentation for primary navigation flows.
Design meaningful secondary actions: When adding secondary actions, use clear, action-oriented text and ensure the action is relevant to the current screen's content. Disable actions when they're not applicable using the isEnabled property.
Override back navigation judiciously: Use overrideNavigateBack only when you need to prevent data loss or handle unsaved changes. Most screens should use the default back navigation behavior to maintain consistent user expectations.

Anchor to limitationsLimitations

Screen components are designed for navigation stack contexts—they can't be used as general layout containers outside of navigation workflows.
Only one secondary action is supported for each screen to maintain clean header layouts that don't overwhelm the interface.
Screen presentation and styling are controlled by the POS navigation system—custom screen transitions or styling beyond the provided options aren't supported.
Navigation parameter handling is limited to the onReceiveParams callback—complex parameter validation or transformation requires custom implementation within the callback.

Was this page helpful?