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.

Choose a version:

List

The list component displays a set of related content as a bulleted or numbered list. Use list to present order details, feature highlights, or step-by-step instructions.

Lists automatically apply markers to each ListItem child. For ordered sequences, set the marker prop to display numbers instead of bullets.

Support

Targets (25)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the List component.

Anchor to accessibilityLabel accessibilityLabel string: A label that describes the purpose or contents of the list. When set, it will be announced to users of assistive technologies such as screen readers to provide additional context.
Anchor to id id string: A unique identifier for the component. Use this to target the component in scripts or stylesheets, or to distinguish it from other instances of the same component.
Anchor to marker marker Default: 'bullet': The type of marker displayed before each list item.

none: No marker is displayed.

bullet: A bullet point marker for unordered lists.

number: A number marker for ordered lists.
Anchor to spacing spacing <> Default: 'base': Adjusts the vertical spacing between list items. Use a design system spacing keyword to control the density of the list.

Marker

'none' | 'bullet' | 'number'

MaybeResponsiveConditionalStyle

A type that represents a value that can be a conditional style. The conditions are based on the viewport size. We highly recommend using the `Style` helper which simplifies the creation of conditional styles.

T | ConditionalStyle<T, ViewportSizeCondition>

ConditionalStyle

A conditional style definition that maps one or more conditions to different values. The `default` value is used as a fallback when none of the conditions in `conditionals` are satisfied.

conditionals
An array of conditional values.
```
ConditionalValue<T, AcceptedConditions>[]
```
default
The default value applied when none of the conditional values specified in `conditionals` are met.
```
T
```

ConditionalValue

A single conditional branch that pairs a set of conditions with the value to apply when those conditions are met.

conditions
The conditions that must be met for the value to be applied. At least one condition must be specified.
```
AcceptedConditions
```
value
The value that will be applied if the conditions are met.
```
T
```

ViewportSizeCondition

A condition that targets layouts based on the inline size (width in horizontal writing modes) of the viewport.

viewportInlineSize
The minimum viewport inline size that the condition must match.
```
{ min: T; }
```

Spacing

A keyword that maps to a predefined spacing value from the design system. Use these instead of pixel values to ensure consistent spacing throughout the UI. - `none`: No spacing (0px). - `extraTight`: The smallest amount of spacing. - `tight`: A compact amount of spacing, suitable for tight layouts. - `base`: The default spacing, appropriate for most layouts. - `loose`: A generous amount of spacing, used to create visual separation. - `extraLoose`: The largest amount of spacing.

'none' | 'extraTight' | 'tight' | 'base' | 'loose' | 'extraLoose'

Anchor to ExamplesExamples

Anchor to Display a list of itemsDisplay a list of items

Present related content as a structured list with bullet or number markers. This example renders a basic list with multiple items.

Display a list of items

A list component displaying multiple items with bullet markers

Display a list of items

import {

reactExtension,

List,

ListItem,

} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(

'customer-account.page.render',

() => <Extension />,

);

function Extension() {

return (

<List>

<ListItem>100% organic cotton</ListItem>

<ListItem>Made in Canada</ListItem>

<ListItem>Machine washable</ListItem>

</List>

);

}

import {extension, List, ListItem} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {

const list = root.createComponent(List, undefined, [

root.createComponent(ListItem, undefined, '100% organic cotton'),

root.createComponent(ListItem, undefined, 'Made in Canada'),

root.createComponent(ListItem, undefined, 'Machine washable'),

]);

root.appendChild(list);

});

React

import {
  reactExtension,
  List,
  ListItem,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
  'customer-account.page.render',
  () => <Extension />,
);

function Extension() {
  return (
    <List>
      <ListItem>100% organic cotton</ListItem>
      <ListItem>Made in Canada</ListItem>
      <ListItem>Machine washable</ListItem>
    </List>
  );
}

JS

import {extension, List, ListItem} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {
  const list = root.createComponent(List, undefined, [
    root.createComponent(ListItem, undefined, '100% organic cotton'),
    root.createComponent(ListItem, undefined, 'Made in Canada'),
    root.createComponent(ListItem, undefined, 'Machine washable'),
  ]);

  root.appendChild(list);
});

Anchor to Best PracticesBest Practices

Use lists to break up chunks of related content to make the information easier for customers to scan.
Phrase list items consistently. Try to start each item with a noun or a verb and be consistent with each item.
Use bullets for a text-only list of related items that don’t need to be in a specific order.
Use numbers for a text-only list of related items when you need to communicate order, priority, or sequence.
Don’t use a marker when only the semantic value of a list matters, such as with a list of links.

Was this page helpful?