---
title: Migrate ExceptionList from Polaris React
description: Learn how to migrate Polaris React ExceptionList to Polaris web components.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/exception-list
  md: >-
    https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/exception-list.md
api_name: app-home
---

# Migrate Exception​List 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.

***

## Choose the destination

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

***

## Map 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. |

***

## Migrate the call site

1. Identify each responsibility currently hidden behind `ExceptionList`: layout, semantics, state, actions, and responsive behavior.

2. Build the documented composition for those responsibilities; don't create a compatibility wrapper that accepts the old API.

3. Reconnect app state and verify the composition at every existing call site.

4. After verification, remove the `ExceptionList` import and any Polaris-only state, wrappers, or helpers that no longer have a caller.

***

## Preserve 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.

***

## Test 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.

***

## Migration example

## Migrating ExceptionList

##### Polaris web components

```tsx
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

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


export function ExceptionListMigrationExample() {

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

***