Migrate List to Polaris list components

Polaris list components display related items as ordered or unordered content. They replace the previous List and ListItem components and are available as <s-ordered-list>, <s-unordered-list>, and s-list-item in API versions 2025-10 and newer.

Anchor to Updated propertiesUpdated properties

The following properties are different in Polaris list components.

Anchor to markermarker

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

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>
  );
}

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 with 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 children.

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>
  );
}

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>
  );
}

Anchor to Removed propertiesRemoved properties

Anchor to spacingspacing

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

Anchor to accessibilityLabelaccessibilityLabel

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