Skip to main content
Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

List

The List component displays structured data in rows with rich content including labels, subtitles, badges, images, and interactive elements. Use it to present organized information with consistent formatting and user interaction capabilities.

List items no longer have dividers as of POS version 10.0.0.

Support
Targets (9)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the List component.

Anchor to data
data
[]
required

An array of ListRow objects that define the content and structure of each row in the list.

Anchor to imageDisplayStrategy
imageDisplayStrategy
'automatic' | 'always' | 'never'
Default: `automatic`

The logic for displaying images or placeholders:

  • automatic: Displays images or placeholders only when it detects that a ListRow has an image source value.
  • always: Displays images or placeholders for all rows, even when image sources are undefined or empty.
  • never: Hides all images and placeholders, creating a text-only list layout.
Anchor to isLoadingMore
isLoadingMore
boolean

A boolean indicating whether more data is being loaded. Set to true when paginating and fetching additional data for the list.

Anchor to listHeaderComponent
listHeaderComponent
RemoteFragment

A header component displayed at the top of the list for additional context or controls.

Anchor to onEndReached
onEndReached
() => void

A callback function executed when the user reaches the end of the list. Use this to trigger requests for loading additional data.

Anchor to title
title
string

A large display title shown at the top of the list.

Anchor to ExamplesExamples

Anchor to Show a product listShow a product list

Display structured data in organized rows with rich content. This example demonstrates a List component showing products with labels, subtitles, images, and interactive elements, providing consistent formatting for collections of items like products, customers, or menu options.

Show a product list

Display structured data in organized rows with rich content. This example demonstrates a List component showing products with labels, subtitles, images, and interactive elements, providing consistent formatting for collections of items like products, customers, or menu options.

Show a product list

import React, {useState} from 'react';
import {
Navigator,
Screen,
List,
Text,
ScrollView,
Section,
ListRowSubtitle,
reactExtension,
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridModal = () => {
const [seeDetails, setSeeDetails] = useState(false);
const listData = [
{
id: 'graphicTees',
leftSide: {
label: 'Graphic Tees',
subtitle: [{content: 'Summer Collection'}, {content: 'Unisex'}] as [
ListRowSubtitle,
ListRowSubtitle?,
],
},
rightSide: {
label: 'Product details',
showChevron: true,
},
onPress: () => setSeeDetails(!seeDetails),
},
{
id: 'denimShorts',
leftSide: {
label: 'Denim Shorts',
subtitle: [{content: 'Summer Collection'}, {content: 'Denim'}] as [
ListRowSubtitle,
ListRowSubtitle?,
],
},
},
];
return (
<Navigator>
<Screen name="ProductList" title="Product List">
<List title="Products" data={listData} />
{seeDetails && (
<ScrollView>
<Section title="Our T-shirts">
<Text>Our shirts are made with 100% organic cotton!</Text>
</Section>
</ScrollView>
)}
</Screen>
</Navigator>
);
};

export default reactExtension('pos.home.modal.render', () => (
<SmartGridModal />
));
import {
Navigator,
Screen,
List,
Text,
ScrollView,
Section,
ListRowSubtitle,
extension,
} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.modal.render', (root, api) => {
let showDetails = false;
const section = root.createComponent(Section, {
title: 'Our T-shirts',
});

const scrollView = root.createComponent(ScrollView);

const triggerShowDetails = () => {
showDetails = !showDetails;
if (showDetails) {
scrollView.append(section);
} else {
scrollView.removeChild(section);
}
};

const listData = [
{
id: 'graphicTees',
leftSide: {
label: 'Graphic Tees',
subtitle: [{content: 'Summer Collection'}, {content: 'Unisex'}] as [
ListRowSubtitle,
ListRowSubtitle?,
],
},
rightSide: {
label: 'Product details',
showChevron: true,
},
onPress: () => triggerShowDetails(),
},
{
id: 'denimShorts',
leftSide: {
label: 'Denim Shorts',
subtitle: [{content: 'Summer Collection'}, {content: 'Denim'}] as [
ListRowSubtitle,
ListRowSubtitle?,
],
},
},
];

const list = root.createComponent(List, {
title: 'Products',
data: listData,
});

const textBlock = root.createComponent(
Text,
null,
'Our shirts are made with 100% organic cotton!',
);

section.append(textBlock);

const screen = root.createComponent(Screen, {
name: 'ProductList',
title: 'Product List',
});

screen.append(list);

if (showDetails) {
scrollView.append(section);
}

screen.append(scrollView);

const navigator = root.createComponent(Navigator);
navigator.append(screen);

root.append(navigator);
});

Anchor to Best practicesBest practices

  • Use images strategically with appropriate display strategies: Choose the right image display strategy based on your content. Use 'automatic' for mixed content, 'always' when consistent image areas improve layout, and 'never' for text-heavy lists where images would be distracting.
  • Implement efficient pagination with onEndReached: Use the onEndReached callback to implement smooth pagination that doesn't disrupt the user experience. Set isLoadingMore appropriately to provide visual feedback during data fetching operations.
  • Apply semantic colors for subtitle information: Use ColorType values in subtitles to convey meaning effectively. Apply TextSuccess for positive states, TextCritical for errors, and TextSubdued for less important information.
  • Design meaningful row interactions: Use onPress callbacks for navigation or detail views, and showChevron to indicate navigation actions. Reserve toggle switches for immediate state changes that don't require navigation.
  • Optimize for touch interfaces: Ensure adequate spacing and touch target sizes by leveraging the List component's built-in touch optimization.

Anchor to LimitationsLimitations

  • List row structure is predefined with specific left and right side layouts—custom row layouts beyond the provided structure aren't supported.
  • Image display is limited to the left side of rows with optional badge overlays—complex image layouts or multiple images for each row aren't available.
  • Toggle switches and interactive elements are limited to the predefined types—custom interactive components within rows require using onPress callbacks and external state management.
Was this page helpful?