To cover the resource list component in depth, we’ll create a customer list as an example. We’ll start by implementing a basic resoure list step by step. Then we’ll customize the built-in resource list item to better display our customers. Finally, we’ll add features to make the list more useful to merchants.
- Development setup (optional)
- A basic resource list
- Building a reusable custom list item
- Adding bulk actions
- Adding sorting
- Adding filtering
- Adding pagination
You can also jump straight to the end result.
Development setup (optional)
If you want to follow along with the code, our setup will be based on Create React App. If you’ve never used Create React App, you can get started by using npx (npm 5.2+):
npx create-react-app my-app
cd my-app
npm start
Your browser will open to localhost:3000 and update as you code. You can learn more about Create React App on GitHub
The main files in our project directory look like this:
my-app/
README.md
node_modules/
package.json
src/
App.css
App.js
App.test.js
index.css
index.js
We’ll open our App.js and replace it with this:
import React, {Component} from 'react';
class App extends Component {
render() {
return <p>Hello world</p>;
}
}
export default App;
You should now see “Hello World” in your browser.
Next, we need to add the React Polaris library to our project. We’ll install it using npm:
npm install @shopify/polaris --save
The last thing before we start building is to import the Polaris styles and the components we’ll need.
import React, { Component } from 'react';
import {
Page,
Card,
ResourceList,
TextStyle,
Avatar,
} from '@shopify/polaris';
import '@shopify/polaris/styles.css';
...
A basic resource list
Let’s start with some sample data. In a real app the customer data would come from an API endpoint or as part of the initial payload from the server.
...
const customers = [
{
id: 341,
url: 'customers/341',
name: 'Mae Jemison',
location: 'Decatur, USA',
},
{
id: 256,
url: 'customers/256',
name: 'Ellen Ochoa',
location: 'Los Angeles, USA',
},
];
...
Notice that we’ve included an id for each customer. This should be a unique identifier from our database.
We also should make sure to sort our items in a way that makes sense to merchants. For this case study, let’s assume we’ve sorted this list by most recent update.
With our sample data in place we can now display a simple resource list:
...
const resourceName = {
singular: 'customer',
plural: 'customers',
};
class App extends Component {
render() {
return (
<Page title="Customers">
<Card>
<ResourceList
resourceName={resourceName}
items={customers}
renderItem={(item) => {
const { id, url, name, location } = item;
const media = <Avatar customer size="medium" name={name} />;
return (
<ResourceList.Item id={id} url={url} media={media} accessibilityLabel={`View details for ${name}`}>
<h3><TextStyle variation="strong">{name}</TextStyle></h3>
<div>{location}</div>
</ResourceList.Item>
);
}}
/>
</Card>
</Page>
);
}
}
...
Let’s take a closer look this code.
Notice we’re providing a prop for the singular and plural name of our resource (“customers”). The resource list component will use these strings to build various pieces of content in the component, such as “Showing 50 customers”.
We’ve broken out our item renderer as a separate function to keep things clean.
Next, we’ll build is a customized resource list item.
Building a reusable custom list item
A list of orders is different than a list of products and is used by merchants differently. As a result, most resource lists benefit from careful choice of content and a customized layout. The best way to do this is to customize the built-in resource list item.
In this section, we’ll build a custom resource list item for customers:
Defining the content
We’ll start by figuring out what information and actions merchants need when working with customers.
- What content is useful to describe the customer?
- What content do merchants need to find a specific customer?
- What content related to the customer will help merchants fulfill an order or make a sale?
The customer name is essential. Their physical location is helpful too, especially for merchants with retail stores or multiple locations. Since orders and customer loyalty are important, the customer’s total order count and total spent are also useful for customer loyalty purposes. Finally, we’ll include an avatar for demonstration purposes. Since customers may not have avatars, consider leaving this out.
This gives us the following content, ranked roughly by importance:
- Customer name
- Location
- Number of orders
- Total spent
- Avatar
Crafting the copy
Resource lists don’t have column headings, so care must be taken to avoid ambiguous copy.
Start by listing out typical values for each piece of content. If the value alone speaks for itself we can use it as-is.
If a value alone is ambiguous, like the number of orders and total spent, add text to make it clear. When possible, use a short phrase rather than a label with a colon.
If a content value is empty for a given item, use a phrase to describe the empty state. For a customer with no orders, use “No orders”. If the value is numeric, “0” may be used. Don’t indicated empty values with em dash (“—”).
When a core content element is empty, show it grayed out using the subdued text style variation.
Using badges as content
The badge component calls strong attention to itself. Showing a badge on every item in a list will distract from the rest of the content.
Whenever possible, use badges conditionally, showing them only when there is an issue or something strongly notable about a particular resource.
Building it
We’ll start by creating a src/components/CustomerListItem directory and adding three files, CustomerListItem.js, CustomerListItem.css, and index.js:
my-app/
README.md
node_modules/
package.json
src/
components/
CustomerListItem/
CustomerListItem.js
CustomerListItem.css
index.js
App.css
App.js
App.test.js
index.css
index.js
In CustomerListItem.js, we’ll add the following:
...
import React from 'react';
import {
ResourceList,
Avatar,
TextStyle,
} from '@shopify/polaris';
import '@shopify/polaris/styles.css';
export default function CustomerListItem(props) {
const { id, url, name, location } = props;
const media = <Avatar customer size="medium" name={name} />;
return (
<div className="CustomerListItem">
<ResourceList.Item id={id} url={url} media={media} accessibilityLabel={`View details for ${name}`}>
<h3><TextStyle variation="strong">{name}</TextStyle></h3>
<div>{location}</div>
</ResourceList.Item>
</div>
);
}
...
This component is also a good example of composition in React. Notice that most of the code here is the same as what we had in our App.js before. However, now we can build a more specific API for our customer list item on top of the basic resource list item we had before.
Notice also that our component is just a regular JavaScript function. This type of component is called a functional component.
Now we’ll add a boilerplate index.js so we can use a more concise import path for it:
import CustomerListItem from './CustomerListItem';
export default CustomerListItem;
In our App.js, we can now import the component like so:
import CustomerListItem from './components/CustomerListItem';
And we can use it in place of our basic resource list item, replacing the entire function we’d passed to renderItem with a one-liner:
renderItem={(customer) => <CustomerListItem {...customer} />}
Let’s also flesh out our sample data to match the content we decided to show in our customized resource list item:
...
const customers = [
{
id: 341,
url: 'customers/341',
avatarSource: 'https://avatars.io/twitter/maejemison',
name: 'Mae Jemison',
location: 'Decatur, USA',
orderCount: 5,
totalSpent: '$497.76',
note: 'This customer is awesome! Make sure to treat them right',
},
{
id: 256,
url: 'customers/256',
avatarSource: 'https://avatars.io/twitter/Astro_Ellen',
name: 'Ellen Ochoa',
location: 'Los Angeles, USA',
orderCount: 1,
totalSpent: '$48.28',
},
{
id: 145,
url: 'customers/145',
avatarSource: 'https://avatars.io/twitter/Astro_Soyeon',
name: 'Yi So-Yeon',
location: 'Gwangju, South Korea',
orderCount: 2,
totalSpent: '$73.98',
},
];
...
Now let’s come back to our customer list item and include the new content.
...
export default function CustomerListItem(props) {
const {
id,
url,
avatarSource,
name,
location,
orderCount = 0,
totalSpent = '$0.00',
} = props;
const media = (
<Avatar customer size="medium" name={name} source={avatarSource} />
);
return (
<div className="CustomerListItem">
<ResourceList.Item id={id} url={url} media={media} accessibilityLabel={`View details for ${name}`}>
<h3>{name}</h3>
<div>{location}</div>
<div>
{orderCount} {orderCount === 1 ? 'order' : 'orders'}
</div>
<div>{totalSpent} spent</div>
</ResourceList.Item>
</div>
);
}
It’s worth noting that we’re not really doing anything with id and url in this component. We’re just “forwarding” them on to ResourceList.Item. We can use the rest and spread operators to make this more resilient, so that CustomerListItem accepts any prop that ResourceList.Item does:
...
export default function CustomerListItem(props) {
const {
avatarSource,
name,
location,
orderCount = 0,
totalSpent = '$0.00',
...rest,
} = props;
const media = (
<Avatar customer size="medium" name={name} source={avatarSource} />
);
return (
<div className="CustomerListItem">
<ResourceList.Item {...rest} media={media} accessibilityLabel={`View details for ${name}`}>
...
We now have our content in place, but it has no layout.
Laying out the content
When laying out details content:
- Place the most distinctive and relevant piece of content at the top left. Set it in bold using the strong text style variation.
- Arrange secondary content to the right, and if necessary, below.
To make use of the available space on wide screens, some content can be arranged in columns. Implementing this requires some care, since items aren’t aware of each other like in a data table. Column alignment works best for content that’s short and predictable in length.
Use the following guidelines:
- Estimate the maximum expected length of the content and add a buffer.
- Set this as the minimum width of the content element. Using a minimum width ensures that if content occasionally exceeds the expected width, it won’t break the layout.
- Choose the alignment of text within the container. Numbers should be right-aligned.
To accommodate smaller screen sizes, follow these guidelines:
- As screen size is reduced, alter the layout by stacking some content elements. Layout changes should happen at the same point for all items.
- As the layout stacks, remove column alignment and any minimum widths.
- On small screens, when multiple pieces of content fit on a single line, use a bullet character to separate them.
When laying out media content:
- If the resource doesn’t have a visual representation, it can be left out.
- Alter size of the media content across screen sizes to improve content density and visual alignment.
Building it
To handle the layout, we’ll need some class names and some wrapping markup.
...
<div className="CustomerListItem">
<ResourceList.Item {...rest} media={media} accessibilityLabel={`View details for ${name}`}>
<h3 className="CustomerListItem__Title">{name}</h3>
<div className="CustomerListItem__Location">{location}</div>
<div className="CustomerListItem__Orders">
<div className="CustomerListItem__OrderCount">
{orderCount} {orderCount === 1 ? 'order' : 'orders'}
</div>
<div className="CustomerListItem__TotalSpent">{totalSpent} spent</div>
</div>
</ResourceList.Item>
</div>
...
And we’ll need to write some CSS. We can import our (so far empty) CSS file from our component.
import './CustomerListItem.css';
In the CSS itself, we’re going to start mobile first. We’ll open up the CSS file we just imported and write some styles for our content elements:
.CustomerListItem {
}
.CustomerListItem__Title {
font-weight: 600;
}
.CustomerListItem__Orders {
display: flex;
align-items: center;
}
.CustomerListItem__Orders > *:not(:first-child)::before {
content: '•';
margin: 0 4px;
color: #919eab;
}
.CustomerListItem__OrderCount {
white-space: nowrap;
}
.CustomerListItem__TotalSpent {
display: flex;
min-width: 0;
justify-content: flex-end;
}
Note that we’ve annotated the colors here to show that they correspond to the Polaris color palette.
Now that we have our small screen layout, we can layer on the layouts for medium and wide screens. This requires some additional wrappers. With this extra markup, it’s a good time to split out some of this out to clean up the code:
...
const profile = (
<div className="CustomerListItem__Profile">
<h3 className="CustomerListItem__Title">{name}</h3>
<div className="CustomerListItem__Location">{location}</div>
</div>
);
const orders = (
<div className="CustomerListItem__Orders">
<div className="CustomerListItem__OrderCount">
{orderCount} {orderCount === 1 ? 'order' : 'orders'}
</div>
<div className="CustomerListItem__TotalSpent">
{totalSpent} spent
</div>
</div>
);
return (
<div className="CustomerListItem">
<ResourceList.Item {...rest} media={media} accessibilityLabel={`View details for ${name}`}>
<div className="CustomerListItem__Main">
{profile}
{orders}
</div>
</ResourceList.Item>
</div>
);
}
Now we can write our styles:
... @media (min-width: 640px) {
.CustomerListItem__Main {
display: flex;
}
.CustomerListItem__Main > *:not(:last-child) {
margin-right: 20px;
}
.CustomerListItem__Orders {
flex: 1;
justify-content: flex-end;
}
.CustomerListItem__Orders > *:not(:first-child)::before {
display: none;
}
.CustomerListItem__OrderCount {
min-width: 80px;
}
.CustomerListItem__TotalSpent {
min-width: 168px;
}
}
@media (min-width: 800px) {
.CustomerListItem__Profile {
display: flex;
flex-wrap: wrap;
}
.CustomerListItem__Profile > *:not(:last-child) {
margin-right: 12px;
}
}
Adding conditional content
Usually each list item contains the same content elements. When a particular resource is in a noteworthy state, additional content can be shown even though it’s not displayed with other items. For example, merchants can add a customer note on the customer’s details page. This is information merchants took time to write down, so it’s worth surfacing in the list.
Unlike a customer’s name, we want to show this customer note only if it’s present. A good way to display conditional content in a resource list item is to use the exception list component (coming soon).
Actions can also be presented conditionally, based on the state of the item. For example, for customers that have an open order, we can highlight this and provide a link to those orders.
Building it
To build this, we’ll add a couple new values to our data and accept them as props:
...
const customers = [
{
id: 341,
url: 'customers/341',
avatarSource: 'https://avatars.io/twitter/maejemison',
name: 'Mae Jemison',
location: 'Decatur, USA',
orderCount: 5,
totalSpent: '$497.76',
note: 'This customer is awesome! Make sure to treat them right',
openOrderCount: 2,
openOrdersUrl: 'orders/1456',
},
...
We’ll need to import some additional components from Polaris…
...
ExceptionList,
Button,
} from '@shopify/polaris';
...
…and use them, along with our new data, to render an exception list and a button under the right conditions:
...
export default function CustomerListItem(props) {
const {
avatarSource,
name,
location,
orderCount = 0,
totalSpent = '$0.00',
note,
openOrderCount,
openOrdersUrl,
...rest,
} = props;
...
let exceptions = [];
let conditionalAction = null;
if (note) {
exceptions.push({ icon: NoteMinor, summary: note });
}
if (openOrderCount !== undefined) {
const label = openOrderCount === 1 ? 'order' : 'orders';
const summary = `${openOrderCount} open ${label}`;
exceptions.push({ status: 'warning', icon: AlertMinor, summary });
conditionalAction = (
<Button plain url={openOrdersUrl} external>
View open orders
</Button>
);
}
const exceptionList = exceptions.length
? (
<div className="CustomerListItem__Exceptions">
<ExceptionList items={exceptions} />
</div>
)
: null;
const conditionalActions = conditionalAction
? (
<div className="CustomerListItem__ConditionalActions">
{conditionalAction}
</div>
)
: null;
return (
<div className="CustomerListItem">
<ResourceList.Item {...rest} media={media} accessibilityLabel={`View details for ${name}`}>
<div className="CustomerListItem__Main">
{profile}
{orders}
</div>
{exceptionList}
{conditionalActions}
</ResourceList.Item>
</div>
);
}
We can finish this off with a couple of simple styles:
...
.CustomerListItem__TotalSpent {
display: flex;
min-width: 0;
justify-content: flex-end;
}
.CustomerListItem__Exceptions {
margin-top: 4px;
}
.CustomerListItem__ConditionalActions {
margin-top: 4px;
}
...
Adding shortcut actions to resource list items
Occasionally a resource has an action that merchants use a lot. Fulfilling orders is a good example. This action is not only popular, it’s the most important action for open orders.
It makes sense to surface this key action from the details page on each list item, but adding this action to each item would be visually repetitive.
Shortcut actions resolve this. They provide a way to promote popular actions by showing them when merchants hover their mouse over a list item. As long as the shortcut action remains available on the resource’s details page, merchants using devices without a mouse can still access them.
Our customer list item can benefit from a shortcut action that lets merchants jump to a customer’s most recent order.
Best practices
Shortcut actions on resource list items must:
- Be present on the resource’s details page so they’re accessible without a mouse.
Shortcut actions should:
- Only be provided for actions that are part of a critical, common merchant task.
- Be available on every item in the list. If the state of a particular resource doesn’t permit the action, it can be left out.
Content guidelines
Shortcut actions should:
Not include the noun from their label if the noun refers to the resource itself. For example, for a list of orders:
Use the full verb + noun formula for actions that refer to another object.
Building it
Shortcut actions can be defined as part of our custom list item, or we can leave it up to the developer using our component to define them for each list, just as they would using ResourceList.Item.
If we were to build a shortcut action into the custom item, we could offer merchants a link to the customer’s most recent order instead of conditional actions. We could add a prop to allow this:
...
openOrderCount,
openOrdersUrl,
latestOrderUrl,
...rest,
} = props;
...
const shortcutActions = openOrdersUrl
? [{ content: 'View latest order', url: openOrdersUrl }]
: null;
return (
<div className="CustomerListItem">
<ResourceList.Item
{...rest}
media={media}
shortcutActions={shortcutActions}
accessibilityLabel={`View details for ${name}`}
>
...
With that, our custom list item is done.
Now let’s save our merchants some time by using more features of the resource list component.
Adding bulk actions to a resource list
Resource lists support optional bulk actions. These allow merchants to select items and perform an action on the selection.
Taking action on many items at once can save merchants a lot of time. However, it can also be difficult to undo. Merchants need to have a high degree of confidence that they aren’t making mistakes in bulk.
- Be deliberate about content elements shown on each list item. Make sure merchants have the content and context they need to be confident about taking action on many resources at once.
- Provide conditional content to make merchants aware when a resource is in a notable or exceptional state.
Because resource lists prioritize acting on individual items, selection checkboxes are hidden by default on small screens to save space for content. A bulk actions mode can be toggled on or off using a button that is made visible at these screen sizes.
Up to two frequently-used bulk actions may be visually promoted outside of the actions menu to improve ease of access and discoverability. On narrower screens, promoted actions move back into the actions menu, but always appear at the top of the list.
Best practices
Bulk actions are optional. If a resource list is always very short, or if there’s no action that makes sense for merchants to perform in bulk, don’t offer bulk actions.
When offering bulk actions, they should:
- Save merchants time (it makes sense to take the action on many resources at once)
- Warn merchants when a bulk action is irreversible using a confirmation modal
- Be shown as promoted bulk actions if they are frequently used
- Be shown in the in order they are most often used
Content guidelines
Be strategic about what type of buik actions you provide to merchants—ask yourself if they’ll save merchants time.
Button and menu item copy
Bulk action buttons and menu items should use the full verb + noun pattern.
Applying the guidelines
For our customers list, we’ve decided to offer the following bulk actions:
| Bulk action copy |
Notes |
| Edit customers |
Opens the bulk editor to allow mass edits. This will be a primary bulk action. |
| Add tags |
|
| Remove tags |
|
| Delete customers |
Should present a confirmation modal to ensure merchants really intend a bulk delete action. |
Building it
We’ll start where we left off previously, with our items being rendered.
Now we’ll add the bulk actions. We’ll need to do several things to get this wired up:
- Define our bulk actions and pass them to the resource list
- Add a handler to respond when merchants begin making a bulk selection
- Add a way to keep track of which items have been selected and make sure our component knows, so it can display the change
The way we keep track of the current selection is with state.
...
class App extends Component {
constructor(props) {
super(props);
this.state = {
selectedItems: [],
}
this.handleSelectionChange = this.handleSelectionChange.bind(this);
}
render() {
const { selectedItems } = this.state;
return (
<ResourceList
resourceName={resourceName}
items={customers}
renderItem={(customer) => <CustomerListItem {...customer} />}
selectedItems={selectedItems}
onSelectionChange={this.handleSelectionChange}
promotedBulkActions={[
{ content: 'Edit customers' },
]}
bulkActions={[
{ content: 'Add tags' },
{ content: 'Remove tags' },
{ content: 'Delete customers' },
]}
/>
);
}
handleSelectionChange(selectedItems) {
this.setState({ selectedItems });
}
}
This allows merchants to make a selection and see the change. Next, we’ll wire up the bulk action buttons.
...
class App extends Component {
constructor(props) {
super(props);
this.state = {
selectedItems: [],
}
this.handleSelectionChange = this.handleSelectionChange.bind(this);
this.handleBulkEdit = this.handleBulkEdit.bind(this);
this.handleBulkAddTags = this.handleBulkAddTags.bind(this);
this.handleBulkRemoveTags = this.handleBulkRemoveTags.bind(this);
this.handleBulkDelete = this.handleBulkDelete.bind(this);
}
render() {
const { selectedItems } = this.state;
return (
<ResourceList
...
promotedBulkActions={[
{ content: 'Edit customers', onAction: this.handleBulkEdit },
]}
bulkActions={[
{ content: 'Add tags', onAction: this.handleBulkAddTags },
{ content: 'Remove tags', onAction: this.handleBulkRemoveTags },
{ content: 'Delete customers', onAction: this.handleBulkDelete },
]}
/>
);
}
handleSelectionChange(selectedItems) {
this.setState({ selectedItems });
}
handleBulkEdit() {
console.log('Opening bulk editor…');
}
handleBulkAddTags() {
console.log('Asynchronously adding tags to customers…');
}
handleBulkRemoveTags() {
console.log('Removing tags from customers…');
}
handleBulkDelete() {
console.log('Handling bulk customer deletion…');
}
}
If you’re new to React or ES2015 you might be wondering about the lines in our constructor that re-assign our handlers. This is a pattern that ensures this in our callbacks is correctly bound to the instance. Doing so in the class constructor helps ensure good performance.
Adding sorting to the list
When merchants sort a list of resources they’re changing the order of the entire set. This is different from filtering, which is when the list of resources is narrowed down to a subset of the original list.
Whether or not you provide sort options, resource lists should have a default sort order that makes sense to merchants and supports their most common tasks.
When you provide sort options to merchants, they’re presented using a select component placed in a standard position in the list header. Each option represents the content element to sort by and a sort direction (ascending or descending).
Best practices
Sort options should:
- Be offered for long lists, especially paginated lists.
- Usually correspond to visible content elements in the list, but don’t have to.
- Avoid offering more than about 8 sort options. Use research to determine the most common ways merchants want to sort a particular list.
Content guidelines
A sort order is always based on a content element, like the customer name or the number of orders. For now, let’s refer to this content element as the “sort basis”.
The basic content formula for sort options is {sort direction} + {sort basis}.
The sort direction should consist of words like “Most”/“Least”, “High”/“Low”, or “Newest”/“Oldest”.
Sort by
Most spent
Least spent
Sort by
High spend
Low spend
Sort by
High conversion
Low conversion
Sort by
Largest conversion
Smallest conversion
The sort basis can consist of multiple words to avoid ambiguity.
Sort by
Most online store visits
Avoid using multiple words for the sort direction. Adding “-est” may help.
Sort by
Newest update
Oldest update
Sort by
Most recent update
Least recent update
If sorting alphabetically, the formula is slightly different. Indicate the sort direction with “A–Z” or “Z–A” at the end of the text, without parentheses. Note the use of an en dash without spaces on either side.
Sort by
Product title A–Z
Product title Z–A
Sort by
Product title (A - Z)
Product title (Z - A)
Sometimes it doesn’t make sense to offer both sort directions, such as when sorting by overall relevance. It’s not a requirement to offer both directions. When offering a single sort direction, the sort direction text can be omitted from the formula.
Sort by
Most relevant
Least relevant
Applying the guidelines
Based on merchant research and following the best practices and content guidelines, we’ve decided to offer the following options for our customer list:
| Sort option |
Copy |
| Date updated (newest first) Default |
Newest update |
| Date updated (oldest first) |
Oldest update |
| Lifetime spent (highest first) |
Most spent |
| Order count (highest first) |
Most orders |
| Customer last name (A–Z) |
Last name A–Z |
| Customer last name (Z–A) |
Last name Z–A |
Building it
We’ll start where we left off, with bulk actions in place. Remember that even before adding sort options, our customer data has already been sorted by most recent update, since this is most helpful to merchants.
As with bulk actions, there are broadly three parts to the implementation:
- Defining the sort options and passing them to our list
- Tracking the currently selected option in state and making sure our list receives the value in
render
- Setting up a handler to respond to and update the state when merchants change the sort option
...
const sortOptions = [
{ label: 'Newest update', value: 'DATE_MODIFIED_DESC' },
{ label: 'Oldest update', value: 'DATE_MODIFIED_ASC' },
{ label: 'Most spent', value: 'TOTAL_SPENT_DESC' },
{ label: 'Most orders', value: 'ORDER_COUNT_DESC' },
{ label: 'Last name A–Z', value: 'ALPHABETICAL_ASC' },
{ label: 'Last name Z–A', value: 'ALPHABETICAL_DESC' },
];
class App extends Component {
constructor(props) {
super(props);
this.state = {
selectedItems: [],
sortValue: 'DATE_MODIFIED_DESC',
}
...
this.handleSortChange = this.handleSortChange.bind(this);
}
render() {
const {selectedItems, sortValue} = this.state;
return (
<ResourceList
...
sortOptions={sortOptions}
sortValue={sortValue}
onSortChange={this.handleSortChange}
/>
);
}
handleSortChange(sortValue) {
this.setState({ sortValue });
}
handleSelectionChange(selectedItems) {
this.setState({ selectedItems });
}
...
We still have one issue though: our items haven’t been re-sorted. To do this, we’ll need to move the items into state. When our sort change handler is called, we’ll build a new array of options and update the items in state.
The actual logic used to build the new items array is dependent on your app, and so the implementation here has been left as a stub. However, it will likely involve fetching new item data from the server.
...
const sortOptions = [
{ label: 'Newest update', value: 'DATE_MODIFIED_DESC' },
{ label: 'Oldest update', value: 'DATE_MODIFIED_ASC' },
{ label: 'Most spent', value: 'TOTAL_SPENT_DESC' },
{ label: 'Most orders', value: 'ORDER_COUNT_DESC' },
{ label: 'Last name A–Z', value: 'ALPHABETICAL_ASC' },
{ label: 'Last name Z–A', value: 'ALPHABETICAL_DESC' },
];
function fetchCustomers() {
return customers;
}
class App extends Component {
constructor(props) {
super(props);
this.state = {
items: customers,
selectedItems: [],
sortValue: 'DATE_MODIFIED_DESC',
}
...
}
render() {
const { items, selectedItems, sortValue } = this.state;
return (
<ResourceList
...
items={items}
...
sortOptions={sortOptions}
sortValue={sortValue}
onSortChange={this.handleSortChange}
/>
);
}
handleSortChange(sortValue) {
const items = fetchCustomers();
this.setState({ items, sortValue });
}
…
Adding filtering to the list
Filtering allows a resource list to be narrowed based on one or more criteria. The resource list component provides a standard filter control.
Best practices and content guidelines
For filtering guidelines, see the corresponding section under the resource list filter control subcomponent:
Applying the guidelines
Based on merchant research and following the best practices and content guidelines, we’ve decided to offer the following filtering options:
| Filter label |
Operator text |
Filter input |
| Money spent |
is greater than |
TextField |
| Number of orders |
is greater than |
TextField |
| Order date |
is |
In the last week
In the last month
In the last three months
In the last year |
| Is an email subscriber |
|
Yes
No |
| Tagged with |
|
Textfield |
| Located in |
country |
Textfield |
Building it
We’ll start with the bulk actions and sorting we added previously and create an object representing the available filters.
...
const availableFilters = [
{
key: 'spentFilter',
label: 'Money spent',
operatorText:'is greater than',
type: FilterType.TextField,
},
{
key: 'orderCountFilter',
label: 'Number of orders',
operatorText:'is greater than',
type: FilterType.TextField,
},
{
key: 'orderDateFilter',
label: 'Order date',
operatorText:'is',
type: FilterType.Select,
options: [
'In the last week',
'In the last month',
'In the last three months',
'In the last year',
],
},
{
key: 'emailSubscriberFilter',
label: 'Is an email subscriber',
type: FilterType.Select,
options: [
'Yes',
'No',
],
},
{
key: 'tagsFilter',
label: 'Tagged with',
type: FilterType.TextField,
},
{
key: 'locationFilter',
label: 'Located in',
operatorText: 'country',
type: FilterType.Select,
},
];
...
Resource list doesn’t accept these available filters directly. Instead, it delegates rendering of the filter control to a separate component. Here we’ll use the built-in resource list filter control.
...
render() {
return (
<ResourceList
...
onSortChange={this.handleSortChange}
filterControl={
<ResourceList.FilterControl
filters={availableFilters}
/>
}
/>
);
}
...
Next, we need to deal with state. We’ll add 2 new properties to our state object. One will handle the text input in the filter control’s search field. The other property will handle the rest of the filters. As we did in our sorting implementation, we’ll add handler methods that call setState to update the UI when merchants change the filters.
...
class App extends Component {
constructor(props) {
super(props);
this.state = {
items: customers,
selectedItems: [],
sortValue: 'DATE_MODIFIED_DESC',
appliedFilters: [],
searchValue: '',
}
...
this.handleFiltersChange = this.handleFiltersChange.bind(this);
this.handleSearchChange = this.handleSearchChange.bind(this);
}
render() {
return (
const {
items,
selectedItems,
sortValue,
appliedFilters,
searchValue
} = this.state;
<ResourceList
...
sortOptions={sortOptions}
sortValue={sortValue}
onSortChange={this.handleSortChange}
filterControl={
<ResourceList.FilterControl
filters={availableFilters}
appliedFilters={appliedFilters}
onFiltersChange={this.handleFiltersChange}
searchValue={searchValue}
onSearchChange={this.handleSearchChange}
/>
}
/>
);
}
handleFiltersChange(appliedFilters) {
const items = fetchCustomers();
this.setState({ items, appliedFilters });
}
handleSearchChange(searchValue) {
const items = fetchCustomers();
this.setState({ items, searchValue });
}
...
}
As with sorting, exactly how the new items array is generated depends on your application, and so the implementation here is left as a stub. However, it will likely involve fetching new item data from the server.
Adding pagination to the list
Resource lists can be long. To make the list digestible, it should be split into pages at 50 items or fewer. Use the pagination component to allow navigation between pages.
Place the pagination immediate below the resource list.
Pagination interacts with bulk actions. When a resource list is paginated, the Select all control selects only the visible items. You can offer the option to select everything in the entire list.
Best practices for pagination
Resource lists should:
- Have a URL for each page.
- Be paginated when they have more than 50 items.
- Disable the pagination component’s previous (or next) button on the first (or last) page in the list.
Align the pagination controls to the left, or centered. The exact layout is flexible.
Building it
The first thing we’ll need to do is build a simple component to handle our pagination layout. Like our custom list item, we’ll add a component to our local components directory:
my-app/
README.md
node_modules/
package.json
src/
components/
CustomerListItem/
CustomerListItem.jsx
CustomerListItem.css
index.js
CustomerListFooter/
CustomerListFooter.jsx
CustomerListFooter.css
index.js
App.css
App.js
App.test.js
index.css
index.js
.CustomerListFooter {
display: flex;
align-items: center;
justify-content: center;
padding: 24px 16px;
border-top: 1px solid #dfe4e8;
}
import React from 'react';
import './CustomerListFooter.css';
export default function CustomerListFooter(props) {
return <div className="CustomerListFooter">{props.children}</div>;
}
import CustomerListFooter from './CustomerListFooter';
export default CustomerListFooter;
Now we can use this component to add our pagination.
import React from 'react';
import {
Page,
Card,
ResourceList,
Pagination,
} from '@shopify/polaris';
import '@shopify/polaris/styles.css';
import CustomerListItem from './components/CustomerListItem';
import CustomerListFooter from './components/CustomerListFooter';
...
class App extends Component {
constructor(props) {
super(props);
this.state = {
items: customers,
selectedItems: [],
sortValue: 'DATE_MODIFIED_DESC',
appliedFilters: [],
searchValue: '',
isFirstPage: true,
isLastPage: false,
}
...
this.handlePreviousPage = this.handlePreviousPage.bind(this);
this.handleNextPage = this.handleNextPage.bind(this);
}
render() {
const {
items,
selectedItems,
sortValue,
appliedFilters,
searchValue,
isFirstPage,
isLastPage,
} = this.state;
const paginationMarkup = items.length > 0
? (
<CustomerListFooter>
<Pagination
hasPrevious={!isFirstPage}
hasNext={!isLastPage}
onPrevious={this.handlePreviousPage}
onNext={this.handleNextPage}
/>
</CustomerListFooter>
)
: null;
return (
<ResourceList
...
/>
{paginationMarkup}
);
}
handlePreviousPage() {
const items = fetchCustomers();
// Todo: figure out how to determine if items represent
// first or last page.
this.setState({ items, isFirstPage: true, isLastPage: false });
}
handleNextPage() {
const items = fetchCustomers();
// Todo: figure out how to determine if items represent
// first or last page.
this.setState({ items, isFirstPage: false, isLastPage: true });
}
...
If we want to allow selecting all items across all pages in our paginated resource list, we can enable this interaction with the hasMoreItems boolean prop.
...
<ResourceList
...
filterControl={
<ResourceList.FilterControl
...
/>
}
hasMoreItems
/>
End result
And with that, our resource list UI is complete. Here is our finished code:
import React, {Component} from 'react';
import {
Page,
Card,
ResourceList,
FilterType,
Pagination,
} from '@shopify/polaris';
import '@shopify/polaris/styles.css';
import CustomerListItem from './components/CustomerListItem';
import CustomerListFooter from './components/CustomerListFooter';
const resourceName = {
singular: 'customer',
plural: 'customers',
};
const customers = [
{
id: 341,
url: 'customers/341',
avatarSource: 'https://avatars.io/twitter/maejemison',
name: 'Mae Jemison',
location: 'Decatur, USA',
orderCount: 5,
totalSpent: '$497.76',
note: 'This customer is awesome! Make sure to treat them right',
openOrderCount: 2,
openOrdersUrl: 'http://google.com',
},
{
id: 256,
url: 'customers/256',
avatarSource: 'https://avatars.io/twitter/Astro_Ellen',
name: 'Ellen Ochoa',
location: 'Los Angeles, USA',
orderCount: 1,
totalSpent: '$48.28',
},
{
id: 145,
url: 'customers/145',
avatarSource: 'https://avatars.io/twitter/Astro_Soyeon',
name: 'Yi So-Yeon',
location: 'Gwangju, South Korea',
orderCount: 2,
totalSpent: '$73.98',
},
];
const sortOptions = [
{label: 'Newest update', value: 'DATE_MODIFIED_DESC'},
{label: 'Oldest update', value: 'DATE_MODIFIED_ASC'},
{label: 'Most spent', value: 'TOTAL_SPENT_DESC'},
{label: 'Most orders', value: 'ORDER_COUNT_DESC'},
{label: 'Last name A–Z', value: 'ALPHABETICAL_ASC'},
{label: 'Last name Z–A', value: 'ALPHABETICAL_DESC'},
];
const availableFilters = [
{
key: 'spentFilter',
label: 'Money spent',
operatorText: 'is greater than',
type: FilterType.TextField,
},
{
key: 'orderCountFilter',
label: 'Number of orders',
operatorText: 'is greater than',
type: FilterType.TextField,
},
{
key: 'orderDateFilter',
label: 'Order date',
operatorText: 'is',
type: FilterType.Select,
options: [
'In the last week',
'In the last month',
'In the last three months',
'In the last year',
],
},
{
key: 'emailSubscriberFilter',
label: 'Is an email subscriber',
type: FilterType.Select,
options: ['Yes', 'No'],
},
{
key: 'tagsFilter',
label: 'Tagged with',
type: FilterType.TextField,
},
{
key: 'locationFilter',
label: 'Located in',
operatorText: 'country',
type: FilterType.Select,
},
];
function fetchCustomers(options) {
return customers;
}
class App extends Component {
constructor(props) {
super(props);
this.state = {
items: customers,
selectedItems: [],
sortValue: 'DATE_MODIFIED_DESC',
appliedFilters: [],
searchValue: '',
isFirstPage: true,
isLastPage: false,
};
this.handleSelectionChange = this.handleSelectionChange.bind(this);
this.handleBulkEdit = this.handleBulkEdit.bind(this);
this.handleBulkAddTags = this.handleBulkAddTags.bind(this);
this.handleBulkRemoveTags = this.handleBulkRemoveTags.bind(this);
this.handleBulkDelete = this.handleBulkDelete.bind(this);
this.handleSortChange = this.handleSortChange.bind(this);
this.handleFiltersChange = this.handleFiltersChange.bind(this);
this.handleSearchChange = this.handleSearchChange.bind(this);
this.handlePreviousPage = this.handlePreviousPage.bind(this);
this.handleSaveFilters = this.handleSaveFilters.bind(this);
this.handlePreviousPage = this.handlePreviousPage.bind(this);
this.handleNextPage = this.handleNextPage.bind(this);
}
render() {
const {
items,
selectedItems,
sortValue,
appliedFilters,
searchValue,
isFirstPage,
isLastPage,
} = this.state;
const paginationMarkup =
items.length > 0 ? (
<CustomerListFooter>
<Pagination
hasPrevious={!isFirstPage}
hasNext={!isLastPage}
onPrevious={this.handlePreviousPage}
onNext={this.handleNextPage}
/>
</CustomerListFooter>
) : null;
return (
<Page title="Customers">
<Card>
<ResourceList
resourceName={resourceName}
items={items}
renderItem={(customer) => <CustomerListItem {...customer} />}
selectedItems={selectedItems}
onSelectionChange={this.handleSelectionChange}
promotedBulkActions={[
{content: 'Edit customers', onAction: this.handleBulkEdit},
]}
bulkActions={[
{content: 'Add tags', onAction: this.handleBulkAddTags},
{content: 'Remove tags', onAction: this.handleBulkRemoveTags},
{content: 'Delete customers', onAction: this.handleBulkDelete},
]}
sortOptions={sortOptions}
sortValue={sortValue}
onSortChange={this.handleSortChange}
filterControl={
<ResourceList.FilterControl
filters={availableFilters}
appliedFilters={appliedFilters}
onFiltersChange={this.handleFiltersChange}
searchValue={searchValue}
onSearchChange={this.handleSearchChange}
additionalAction={{
content: 'Save',
onAction: this.handleSaveFilters,
}}
/>
}
hasMoreItems
/>
{paginationMarkup}
</Card>
</Page>
);
}
handlePreviousPage() {
const items = fetchCustomers();
// Todo: figure out how to determine if items represent
// first or last page.
this.setState({items, isFirstPage: true, isLastPage: false});
}
handleNextPage() {
const items = fetchCustomers();
// Todo: figure out how to determine if items represent
// first or last page.
this.setState({items, isFirstPage: false, isLastPage: true});
}
handleFiltersChange(appliedFilters) {
const items = fetchCustomers();
this.setState({items, appliedFilters});
}
handleSearchChange(searchValue) {
const items = fetchCustomers();
this.setState({items, searchValue});
}
handleSortChange(sortValue) {
const items = fetchCustomers();
this.setState({items, sortValue});
}
handleSelectionChange(selectedItems) {
this.setState({selectedItems});
}
handleBulkEdit() {
console.log('Opening bulk editor…');
}
handleBulkAddTags() {
console.log('Asynchronously adding tags to customers…');
// A Flash message should be displayed to confirm that async process
// has started.
}
handleBulkRemoveTags() {
console.log('Removing tags from customers…');
}
handleBulkDelete() {
console.log('Handling bulk customer deletion…');
// Since this action destroys resources in bulk, show a
// confirmation modal (“Are you sure you want to delete {n}
// customers”) before completing the action.
}
handleSaveFilters() {
console.log('Saving current filters…');
}
}
export default App;
