Migrate ExceptionList from Polaris React

Compose a semantic unordered list with inline text primitives. Keep each exception understandable without relying on an icon or color alone. Use a banner separately only when the complete page or task needs prominent feedback.

Anchor to Choose the destinationChoose the destination

Polaris React	Polaris web components	Migration type
`ExceptionList`	`s-unordered-list`, `s-paragraph`, and inline text composition	Compose

Anchor to Map exception itemsMap exception items

Polaris React	Polaris web components	Migration notes
`items`	`s-unordered-list` with `s-list-item` children	Render each exception as a separate semantic list item.
`item.title` and `item.description`	Strong and supporting text in one `s-paragraph`	Preserve the inline title, separator, and recovery step. Let the paragraph wrap naturally only when space is constrained.
`item.status`	Optional tone or icon plus complete text	Don't use color or an icon as the only severity signal.

Anchor to Migrate the call siteMigrate the call site

Identify each responsibility currently hidden behind ExceptionList: layout, semantics, state, actions, and responsive behavior.
Build the documented composition for those responsibilities; don't create a compatibility wrapper that accepts the old API.
Reconnect app state and verify the composition at every existing call site.
After verification, remove the ExceptionList import and any Polaris-only state, wrappers, or helpers that no longer have a caller.

Anchor to Preserve these behaviorsPreserve these behaviors

Information hierarchy, reading order, and accessible relationships.
App-owned state and every action or navigation outcome.
Responsive behavior and focus order across the composed elements.

Anchor to Test and remove Polaris ReactTest and remove Polaris React

Test the complete ExceptionList composition at each responsive size used by the app. Verify reading and focus order, accessible relationships, keyboard interaction, and every action outcome.

Don't remove @shopify/polaris while another component still imports it. Once all call sites are migrated, remove the package and its provider-level setup, then run the app's full test suite.

Anchor to Migration exampleMigration example

Migrating ExceptionList

export function ExceptionListMigrationExample() {

return (

<s-unordered-list>

<s-list-item>

<s-paragraph>

<s-text type="strong">Payment failed</s-text>

<s-text color="subdued"> – Update the payment method.</s-text>

</s-paragraph>

</s-list-item>

</s-unordered-list>

);

}

import {ExceptionList} from '@shopify/polaris';

export function ExceptionListMigrationExample() {

return (

);

}

Polaris web components

export function ExceptionListMigrationExample() {
  return (
    <s-unordered-list>
      <s-list-item>
        <s-paragraph>
          <s-text type="strong">Payment failed</s-text>
          <s-text color="subdued"> – Update the payment method.</s-text>
        </s-paragraph>
      </s-list-item>
    </s-unordered-list>
  );
}

Polaris React

import {ExceptionList} from '@shopify/polaris';


export function ExceptionListMigrationExample() {

  return (
    <ExceptionList items={[{title: 'Payment failed', description: 'Update the payment method.'}]} />
  );
}

Preview

Was this page helpful?