---
title: Migrate List to Polaris list components
description: >-
  Learn how to migrate the List component to Polaris web components in checkout
  and customer account UI extensions.
source_url:
  html: 'https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/list'
  md: >-
    https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/list.md
---

# Migrate List to Polaris list components

Polaris list components display related items as ordered or unordered content. They replace the previous [`List`](https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/ui-components/typography-and-content/list) and [`ListItem`](https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/ui-components/typography-and-content/listitem) components and are available as [`<s-ordered-list>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/ordered-list), [`<s-unordered-list>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/unordered-list), and [`s-list-item`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/ordered-list#list%20item) in API versions 2025-10 and newer.

***

## Updated properties

The following properties are different in Polaris list components.

### marker

The previous `List` `marker` prop has been replaced by choosing the appropriate Polaris list component.

| Previous pattern | New pattern | Migration notes |
| - | - | - |
| `<List marker="bullet">` | [`<s-unordered-list>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/unordered-list) | Use unordered list for bulleted content. |
| `<List marker="number">` | [`<s-ordered-list>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/ordered-list) | Use ordered list for numbered content. |
| `<List marker="none">` | Use [`s-stack`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/stack) with [`accessibilityRole`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/stack#properties-propertydetail-accessibilityrole) | Use semantic roles when you need list structure without built-in markers. |

## Migrating marker to Polaris list components

##### Latest (Preact)

```jsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return (
    <s-unordered-list>
      <s-list-item>Free shipping on orders over $50</s-list-item>
      <s-list-item>30-day return policy</s-list-item>
      <s-list-item>Secure checkout</s-list-item>
    </s-unordered-list>
  );
}
```

##### Pre-Polaris (2025-07)

```jsx
import {
  reactExtension,
  List,
  ListItem,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  return (
    <List marker="bullet">
      <ListItem>Free shipping on orders over $50</ListItem>
      <ListItem>30-day return policy</ListItem>
      <ListItem>Secure checkout</ListItem>
    </List>
  );
}
```

If you previously used `marker="none"`, use [`s-stack`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/stack) with [`accessibilityRole`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/stack#properties-propertydetail-accessibilityrole) to preserve list semantics without built-in bullets or numbers. Set the stack role to `ordered-list` or `unordered-list`, and use [`s-list-item`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/ordered-list#list%20item) children.

## Migrating marker=none

##### Latest (Preact)

```jsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return (
    <s-stack accessibilityRole="unordered-list" gap="base">
      <s-list-item>Product features</s-list-item>
      <s-list-item>Specifications</s-list-item>
    </s-stack>
  );
}
```

##### Pre-Polaris (2025-07)

```jsx
import {
  reactExtension,
  List,
  ListItem,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  return (
    <List marker="none">
      <ListItem>Product features</ListItem>
      <ListItem>Specifications</ListItem>
    </List>
  );
}
```

***

## Removed properties

### spacing

Polaris list components no longer support `spacing`. Lists now use built-in spacing between items that you can't customize.

### accessibility​Label

Polaris list components no longer support `accessibilityLabel` directly. Instead, provide enough context in surrounding content so customers understand what the list contains.

***