---
title: Home screen (smart grid)
description: >-
  The smart grid is the first screen merchants see when they open the POS app.
  It provides quick access to essential functions and serves as the starting
  point for merchant activities.
api_version: 2024-04
api_name: pos-ui-extensions
source_url:
  html: 'https://shopify.dev/docs/api/pos-ui-extensions/2024-04/targets/home-screen'
  md: >-
    https://shopify.dev/docs/api/pos-ui-extensions/2024-04/targets/home-screen.md
---

# Home screen (smart grid)

The smart grid is the first screen merchants see when they open [the POS app](https://apps.shopify.com/shopify-pos). It provides quick access to essential functions and serves as the starting point for merchant activities.

### Use cases

* **Sales analytics:** Display summaries and launch detailed reporting dashboards.
* **Inventory management:** Access scanning tools, stock alerts, and bulk operations.
* **Customer engagement:** Launch profile management and enrollment workflows.
* **Promotions:** Configure discounts and manage campaign status.

![Home screen targets overview](https://shopify.dev/assets/assets/images/api/pos-ui-extensions/targets-overview-images/home-overview-BPxYFUox.png)

***

## Home screen targets

Use these targets for high-frequency actions, status displays, or entry points to workflows that merchants need daily.

### Home screen tile target

`pos.home.tile.render`

Renders a single interactive tile component on the POS home screen's smart grid. The tile appears once during home screen initialization and remains persistent until navigation occurs. Use this target for high-frequency actions, status displays, or entry points to workflows that merchants need daily.

Extensions at this target can dynamically update properties like enabled state and badge values in response to cart changes or device conditions. Tiles typically invoke `api.action.presentModal()` to launch the companion [modal](#home-screen-action-modal-) for complete workflows.

Examples

### Examples

* #### Create an interactive smart grid tile

  ##### Description

  Render a tile on the POS home screen that launches your extension's modal. This example shows how to create a tile with title, subtitle, and press handler using the \`pos.home.tile.render\` target, providing quick access to your app from the smart grid.

  ##### React

  ```tsx
  import React from 'react'

  import { Tile, reactExtension, useApi } from '@shopify/ui-extensions-react/point-of-sale'

  const TileComponent = () => {
  const api = useApi()
  return (
  <Tile
  title='My app'
  subtitle='SmartGrid react Extension'
  onPress={() => {
  api.action.presentModal()
  }}
  enabled
  />
  )
  }

  export default reactExtension('pos.home.tile.render', () => {
  return <TileComponent />
  })
  ```

  ##### TS

  ```ts
  import {extension, Tile} from '@shopify/ui-extensions/point-of-sale';

  export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
  title: 'My app',
  subtitle: 'SmartGrid vanilla-js Extension',
  onPress: () => api.action.presentModal(),
  enabled: true,
  });

  root.append(tile);
  });
  ```

### Home screen action (modal) target

`pos.home.modal.render`

Renders a full-screen modal interface launched from smart grid tiles. The modal appears when users tap a companion [tile](#home-screen-tile-). Use this target for complete workflow experiences that require more space and functionality than the tile interface provides, such as multi-step processes, detailed information displays, or complex user interactions.

Extensions at this target support full navigation hierarchies with multiple screens, scroll views, and interactive components to handle sophisticated workflows.

Examples

### Examples

* #### Create a full-screen modal interface

  ##### Description

  Build a modal view that launches from a smart grid tile to provide complete workflows and multi-screen experiences. This example demonstrates creating a basic modal with navigation, screen, and scrollable content—the foundation for building comprehensive POS extension experiences.

  ##### React

  ```tsx
  import React from 'react'

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

  const Modal = () => {
  return (
  <Navigator>
  <Screen name='HelloWorld' title='Hello World!'>
  <ScrollView>
  <Text>Welcome to the extension!</Text>
  </ScrollView>
  </Screen>
  </Navigator>
  )
  }

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

  ##### TS

  ```ts
  import {
  Navigator,
  Screen,
  ScrollView,
  Text,
  extension,
  } from '@shopify/ui-extensions/point-of-sale';

  export default extension('pos.home.modal.render', (root) => {
  const navigator = root.createComponent(Navigator);
  const screen = root.createComponent(Screen, {
  name: 'HelloWorld',
  title: 'Hello World!',
  });
  const scrollView = root.createComponent(ScrollView);
  const text = root.createComponent(Text);

  text.append('Welcome to the extension!');
  scrollView.append(text);
  screen.append(scrollView);
  navigator.append(screen);
  root.append(navigator);
  });
  ```

***

## Best practices

* **Update tiles immediately:** Update tile appearance when data changes to show the system responds to actions.
* **Show clear confirmations:** Display success or error messages in modals with specific details like "Discount applied successfully."
* **Use toasts for quick feedback:** Use toast messages for successful actions or errors without disrupting workflows.
* **Communicate error states clearly:** Show unavailable functionality through disabled tiles, modal messages, or error text explaining next steps.
* **Write action-oriented titles:** Use specific titles like "Apply loyalty discount" instead of generic labels like "Loyalty app."
* **Provide contextual information:** Show eligibility requirements, status, or context through subtitles and badge values.

***

## Limitations

You can only render one [Tile](https://shopify.dev/docs/api/pos-ui-extensions/2024-04/ui-components/actions/tile) component for each POS UI extension.

***