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

# Migrate Card from Polaris React

Choose `s-section` for a normal page region and the app card pattern when the card itself is a reusable, action-oriented composition. Avoid wrapping every block in a card.

***

## Choose the destination

| Polaris React | Polaris web components | Migration type |
| - | - | - |
| `Card` | [`s-section`](https://shopify.dev/docs/api/app-home/web-components/layout-and-structure/section) or [app card pattern](https://shopify.dev/docs/api/app-home/patterns/compositions/app-card) | Compose |

***

## Map card structure

| Polaris React usage | Polaris web components | Migration notes |
| - | - | - |
| Card as a page region | `s-section` | Preserve the section heading and related controls. Don't add a wrapper only to reproduce a border. |
| Card as a reusable resource summary | App card pattern | Migrate the title, description, metadata, and action as one composition. |
| `Card.Section` or custom padding | Separate sections, `s-stack`, or `s-box padding` | Split only when a region has its own responsibility, and use documented spacing values. |

***

## Map Card properties

| Polaris React | Polaris web components | Migration notes |
| - | - | - |
| `padding` | `padding="base"` or `"none"` on `s-section`, or a supported `padding` value on `s-box` | Use `s-section padding="none"` for edge-to-edge content, then wrap only inset content in `s-box padding="base"`. Don't translate numeric tokens mechanically. |
| `background="subdued"` | A pattern that owns a subdued surface, or `s-box background="subdued"` inside the semantic section | Don't add a background only to reproduce every old card boundary. Keep the section heading and hierarchy clear. |
| `roundedAbove` | Remove | Section surfaces and App Home patterns own their responsive shape. Don't recreate breakpoint-based corner rounding in app CSS. |
| `children` | Section or pattern content | Preserve heading, actions, and reading order while removing wrappers that existed only for card styling. |

***

## Migrate the call site

1. Identify each responsibility currently hidden behind `Card`: 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 `Card` 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 `Card` 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 Card

##### Polaris web components

```tsx
export function CardMigrationExample() {
  return (
    <><s-section heading="Product details"><s-paragraph>Manage product information.</s-paragraph></s-section></>
  );
}
```

##### Polaris React

```tsx
import {Card, Text} from '@shopify/polaris';

export function CardMigrationExample() {
  return (
    <Card>
      <Text as="h2" variant="headingSm">Product details</Text>
      <Text as="p">Manage product information.</Text>
    </Card>
  );
}
```

***