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.

Anchor to Choose the destinationChoose the destination

Polaris React	Polaris web components	Migration type
`Card`	`s-section` or app card pattern	Compose

Anchor to Map card structureMap 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.

Anchor to Map Card propertiesMap 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.

Anchor to Migrate the call siteMigrate the call site

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

Anchor to Migration exampleMigration example

Migrating Card

export function CardMigrationExample() {

return (

<><s-section heading="Product details"><s-paragraph>Manage product information.</s-paragraph></s-section></>

);

}

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>

);

}

Polaris web components

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

Polaris React

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

Preview

Was this page helpful?