Choose a version:

Home screen (smart grid)

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.

Anchor to Use casesUse 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.

Anchor to Home screen targetsHome screen targets

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

Anchor to Home screen tile ,[object Object]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 for complete workflows.

Support

Components (1)

APIs (8)

Supported components

Tile

Available APIs

Examples

import React from 'react';

import {

Tile,

reactExtension,

useApi,

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

const TileComponent = () => {

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

return (

<Tile

title="My app"

subtitle="SmartGrid react Extension"

onPress={() => {

api.action.presentModal();

}}

enabled

);

};

export default reactExtension('pos.home.tile.render', () => {

return <TileComponent />;

});

Examples

Create a smart grid tile

Description

Add an interactive tile to the POS home screen smart grid for high-frequency actions. This example shows how to create a persistent tile that can dynamically update its enabled state and badge values, providing merchants with quick access to daily workflows and status displays.

React

import React from 'react';

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

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

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

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

Anchor to Home screen action (modal) ,[object Object]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. 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.

Support

Components (32)

APIs (9)

Examples

import React from 'react'

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

const Modal = () => {

return (

<Text>Welcome to the extension!</Text>

</ScrollView>

</Screen>

</Navigator>

)

}

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

Examples

Create a full-screen modal from a tile

Description

Build a full-screen modal interface launched from smart grid tiles. This example demonstrates creating a modal that appears when merchants tap a tile, supporting complete workflows with multiple screens, scroll views, and interactive components for sophisticated tasks.

React

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

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

Anchor to Best practicesBest 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.

Anchor to LimitationsLimitations

You can only render one Tile component for each POS UI extension.

Was this page helpful?