Choose a version:

Screen
component

A component used in the root of a modal extension to define a screen.

Anchor to screenScreen

Anchor to name name string required: Used to identify this screen as a destination in the navigation stack.
Anchor to title title string required: The title of the screen which will be displayed on the UI.
Anchor to isLoading isLoading boolean: Displays a loading indicator when true. Set this to true when performing an asynchronous task, and then to false when the data becomes available to the UI.
Anchor to onNavigate onNavigate () => void: Triggered when the screen is navigated to.
Anchor to onNavigateBack onNavigateBack () => void: Triggered when the user navigates back from this screen. Runs after screen is unmounted.
Anchor to onReceiveParams onReceiveParams (params: any) => void: A callback that gets triggered when the navigation event completes and the screen receives the parameters.
Anchor to overrideNavigateBack overrideNavigateBack () => void: A callback that allows you to override the secondary navigation action. Runs when screen is mounted.
Anchor to presentation presentation: Dictates how the Screen will be presented when navigated to.
Anchor to secondaryAction secondaryAction: Displays a secondary action button on the screen.

ScreenProps

Represents a screen in the navigation stack.

isLoading
Displays a loading indicator when `true`. Set this to `true` when performing an asynchronous task, and then to false when the data becomes available to the UI.
```
boolean
```
name
Used to identify this screen as a destination in the navigation stack.
```
string
```
onNavigate
Triggered when the screen is navigated to.
```
() => void
```
onNavigateBack
Triggered when the user navigates back from this screen. Runs after screen is unmounted.
```
() => void
```
onReceiveParams
A callback that gets triggered when the navigation event completes and the screen receives the parameters.
```
(params: any) => void
```
overrideNavigateBack
A callback that allows you to override the secondary navigation action. Runs when screen is mounted.
```
() => void
```
presentation
Dictates how the `Screen` will be presented when navigated to.
```
ScreenPresentationProps
```
secondaryAction
Displays a secondary action button on the screen.
```
SecondaryActionProps
```
title
The title of the screen which will be displayed on the UI.
```
string
```

export interface ScreenProps {
  /**
   * Used to identify this screen as a destination in the navigation stack.
   */
  name: string;
  /**
   * The title of the screen which will be displayed on the UI.
   */
  title: string;
  /**
   * Displays a loading indicator when `true`.
   * Set this to `true` when performing an asynchronous task, and then to false when the data becomes available to the UI.
   */
  isLoading?: boolean;
  /**
   * Dictates how the `Screen` will be presented when navigated to.
   */
  presentation?: ScreenPresentationProps;
  /**
   * Displays a secondary action button on the screen.
   */
  secondaryAction?: SecondaryActionProps;
  /**
   * Triggered when the screen is navigated to.
   */
  onNavigate?: () => void;
  /**
   * Triggered when the user navigates back from this screen. Runs after screen is unmounted.
   */
  onNavigateBack?: () => void;
  /**
   * A callback that allows you to override the secondary navigation action. Runs when screen is mounted.
   */
  overrideNavigateBack?: () => void;
  /**
   * A callback that gets triggered when the navigation event completes and the screen receives the parameters.
   */
  onReceiveParams?: (params: any) => void;
}

ScreenPresentationProps

Represents the presentation of a screen in the navigation stack.

sheet
Displays the screen from the bottom on `navigate` when `true`.
```
boolean
```

export interface ScreenPresentationProps {
  /**
   * Displays the screen from the bottom on `navigate` when `true`.
   */
  sheet?: boolean;
}

SecondaryActionProps

Represents the secondary action button of a screen in the navigation stack.

isEnabled
Sets whether the action can be tapped.
```
boolean
```
onPress
Triggered when the secondary action button is pressed.
```
() => void
```
text
Displays the name of the secondary action in the action bar.
```
string
```

export interface SecondaryActionProps {
  /**
   * Displays the name of the secondary action in the action bar.
   */
  text: string;
  /**
   * Triggered when the secondary action button is pressed.
   */
  onPress: () => void;
  /**
   * Sets whether the action can be tapped.
   */
  isEnabled?: boolean;
}

Was this section helpful?

Anchor to screenpresentationpropsScreenPresentationProps

Anchor to sheet sheet boolean: Displays the screen from the bottom on navigate when true.

ScreenPresentationProps

Represents the presentation of a screen in the navigation stack.

sheet
Displays the screen from the bottom on `navigate` when `true`.
```
boolean
```

export interface ScreenPresentationProps {
  /**
   * Displays the screen from the bottom on `navigate` when `true`.
   */
  sheet?: boolean;
}

Was this section helpful?

Anchor to secondaryactionpropsSecondaryActionProps

Anchor to onPress onPress () => void required: Triggered when the secondary action button is pressed.
Anchor to text text string required: Displays the name of the secondary action in the action bar.
Anchor to isEnabled isEnabled boolean: Sets whether the action can be tapped.

SecondaryActionProps

Represents the secondary action button of a screen in the navigation stack.

isEnabled
Sets whether the action can be tapped.
```
boolean
```
onPress
Triggered when the secondary action button is pressed.
```
() => void
```
text
Displays the name of the secondary action in the action bar.
```
string
```

export interface SecondaryActionProps {
  /**
   * Displays the name of the secondary action in the action bar.
   */
  text: string;
  /**
   * Triggered when the secondary action button is pressed.
   */
  onPress: () => void;
  /**
   * Sets whether the action can be tapped.
   */
  isEnabled?: boolean;
}

Was this section helpful?

Navigate to another 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 />);

examples

Navigate to another screen

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

Preview

Anchor to examplesExamples

Navigating using NavigationAPI with Screens within Navigators

Anchor to example-navigate-to-another-screen-with-parametersNavigate to another screen with parameters

Anchor to example-navigate-to-another-screen-with-sheet-presentationNavigate to another screen with sheet presentation

Was this section helpful?

Navigate to another screen with parameters

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

examples

Navigate to another screen with parameters

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

Navigate to another screen with sheet presentation

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

Screencomponent

Anchor to screenScreen

ScreenProps

ScreenPresentationProps

SecondaryActionProps

Anchor to screenpresentationpropsScreenPresentationProps

ScreenPresentationProps

Anchor to secondaryactionpropsSecondaryActionProps

SecondaryActionProps

examples

Navigate to another screen

React

TS

Preview

Anchor to examplesExamples

examples

Navigate to another screen with parameters

React

TS

Navigate to another screen with sheet presentation

React

TS

Screen
component