---
title: Screen
description: A component used in the root of a modal extension to define a screen.
api_version: 2024-04
api_name: pos-ui-extensions
source_url:
  html: 'https://shopify.dev/docs/api/pos-ui-extensions/2024-04/components/screen'
  md: 'https://shopify.dev/docs/api/pos-ui-extensions/2024-04/components/screen.md'
---

# Screencomponent

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

## Screen

* name

  string

  required

  Used to identify this screen as a destination in the navigation stack.

* title

  string

  required

  The title of the screen which will be displayed on the UI.

* 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.

* presentation

  ScreenPresentationProps

  Dictates how the `Screen` will be presented when navigated to.

* secondaryAction

  SecondaryActionProps

  Displays a secondary action button on the screen.

* onNavigate

  () => void

  Triggered when the screen is navigated to.

* onNavigateBack

  () => void

  Triggered when the user navigates back from this screen. Runs after screen is unmounted.

* overrideNavigateBack

  () => void

  A callback that allows you to override the secondary navigation action. Runs when screen is mounted.

* onReceiveParams

  (params: any) => void

  A callback that gets triggered when the navigation event completes and the screen receives the parameters.

### ScreenPresentationProps

Represents the presentation of a screen in the navigation stack.

* sheet

  Displays the screen from the bottom on \`navigate\` when \`true\`.

  ```ts
  boolean
  ```

```ts
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.

* text

  Displays the name of the secondary action in the action bar.

  ```ts
  string
  ```

* onPress

  Triggered when the secondary action button is pressed.

  ```ts
  () => void
  ```

* isEnabled

  Sets whether the action can be tapped.

  ```ts
  boolean
  ```

```ts
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;
}
```

## ScreenPresentationProps

* sheet

  boolean

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

## SecondaryActionProps

* text

  string

  required

  Displays the name of the secondary action in the action bar.

* onPress

  () => void

  required

  Triggered when the secondary action button is pressed.

* isEnabled

  boolean

  Sets whether the action can be tapped.

### Examples

* #### Navigate to another screen

  ##### 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 (
      <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

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

![](https://shopify.dev/images/templated-apis-screenshots/pos-ui-extensions/2024-04/screen-default.png)

## Examples

Navigating using NavigationAPI with Screens within Navigators

### Examples

* #### Navigate to another screen with parameters

  ##### 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 (
      <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

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

  ```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 (
      <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

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