Resource list

A resource list displays a collection of objects of the same type, like products or customers. The main job of a resource list is to help merchants find an object and navigate to a full-page representation of it.

Resource list component examples

A resource list with simple items and no bulk actions, sorting, or filtering.

import {
} from '@shopify/polaris';
import React from 'react';

function ResourceListExample() {
  return (
        resourceName={{singular: 'customer', plural: 'customers'}}
            id: '100',
            url: '#',
            name: 'Mae Jemison',
            location: 'Decatur, USA',
            id: '200',
            url: '#',
            name: 'Ellen Ochoa',
            location: 'Los Angeles, USA',
        renderItem={(item) => {
          const {id, url, name, location} = item;
          const media = <Avatar customer size="md" name={name} />;

          return (
              accessibilityLabel={`View details for ${name}`}
              <Text variant="bodyMd" fontWeight="bold" as="h3">


interface ResourceListProps

Item data; each item is passed to renderItem.


Whether to remove all padding around the filter controls. Should be true if using Filters, and false if using LegacyFilters.


The markup to display when no resources exist yet. Renders when set and items is empty.


The markup to display when no results are returned on search or filter of the list. Renders when `filterControl` is set, items are empty, and `emptyState` is not set.

Defaults to EmptySearchResult.

resourceName?{ singular: string; plural: string; }

Name of the resource, such as customers or products.

promotedBulkActions?( | BulkAction)[]

Up to 2 bulk actions that will be given more prominence.

bulkActions?( | BulkAction)[]

Actions available on the currently selected items.

selectedItems?string[] | 'All'

Collection of IDs for the currently selected items.


Whether or not the list has filter(s) applied.


Renders a Select All button at the top of the list and checkboxes in front of each list item. For use when bulkActions aren't provided. *.


Whether or not there are more items than currently set on the items prop. Determines whether or not to set the paginatedSelectAllAction and paginatedSelectAllText props on the BulkActions component.


Overlays item list with a spinner while a background action is being performed.


Boolean to show or hide the header.


Total number of resources.


Current value of the sort control.

sortOptions?string | []

Collection of sort options to choose from.


ReactNode to display instead of the sort control.


Custom header text displayed above the list instead of the resource count.

onSortChange?(selected: string, id: string) => void

Callback when sort option is changed.

onSelectionChange?(selectedItems: string[] | 'All') => void

Callback when selection is changed.

renderItem(item: TItemType, id: string, index: number) => React.ReactNode

Function to render each list item, must return a ResourceItem component.

idForItem?(item: TItemType, index: number) => string

Function to customize the unique ID for each item.

resolveItemId?(item: TItemType) => string

Function to resolve the ids of items.

pagination?Omit<, 'type'>

Properties to enable pagination at the bottom of the list.

Resource lists can also:

  • Support customized list items
  • Include bulk actions so merchants can act on multiple objects at once
  • Support sorting and filtering of long lists
  • Be paired with pagination to make long lists digestible


Using a resource list in a project involves combining the following components and subcomponents:

  • ResourceList
  • ResourceItem or a customized list item
  • Filters (optional)
  • Pagination component (optional)

The resource list component provides the UI elements for list sorting, filtering, and pagination, but doesn’t provide the logic for these operations. When a sort option is changed, filter added, or second page requested, you’ll need to handle that event (including any network requests) and then update the component with new props.


Shopify is organized around objects that represent merchants businesses, like customers, products, and orders. Each individual order, for example, is given a dedicated page that can be linked to. In Shopify, we call these types of objects resources, and we call the object’s dedicated page its details page.


Take orders as an example. Merchants may have a lot of them. They need a way to scan their orders, see what state they’re in and find out which ones need action first. In other words, they need a way find an individual order, call up more information about it, and take action on it.


Resource lists function as:

  • A content format, presenting a set of individual resources in a compact form
  • A system for taking action on one or more individual resources
  • A way to navigate to an individual resource’s details page

Because a details page displays all the content and actions for an individual resource, you can think of a resource list as a summary of these details pages. In this way resource lists bridge a middle level in Shopify’s navigation hierarchy.

A resource list isn’t a data table

On wide screens, a resource list often looks like a table, especially if some content is aligned in columns. Despite this, resource lists and data tables have different purposes.

A data table is a form of data visualization. It works best to present highly structured data for comparison and analysis.

If your use case is more about visualizing or analyzing data, use the data table component. If your use case is more about finding and taking action on objects, use a resource list.

Best practices

Resource lists can live in many places in Shopify. You could include a short resource list in a card summarizing recent marketing activities. You could also dedicate an entire page to a resource list like Shopify’s main products list.

Resource lists should:

  • Have items that perform an action when clicked. The action should navigate to the resource’s details page or otherwise provide more detail about the item.
  • Customize the content and layout of their list items to support merchants’ needs.
  • Support sorting if the list can be long, and especially if different merchant tasks benefit from different sort orders.
  • Support filtering if the list can be long.
  • Paginate when the current list contains more than 50 items.
  • Use the skeleton page component on initial page load for the rest of the page if the loading prop is true and items are processing.

Resource lists can optionally:

  • Provide bulk actions for tasks that are often applied to many list items at once. For example, merchants may want to add the same tag to a large number of products.

Content guidelines

Resource lists should:

  • Identify the type of resource, usually with a heading
  • Products
  • Showing 50 products
  • No heading
  • Indicate when not all members of a resource are being shown. For a card summarizing and linking to recently purchased products:
  • Popular products this week
  • Products

  • To present structured data for comparison and analysis, like when helping merchants to gain insights or review analytics, use the data table component
  • To display a simple list of related content, use the list component

    On this page