---
title: Migrate Layout from Polaris React
description: >-
  Replace Polaris React Layout with s-page regions and explicit grid or stack
  layouts.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/layout
  md: >-
    https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/layout.md
api_name: app-home
---

# Migrate Layout from Polaris React

Replace Polaris React `Layout` with the [`s-page`](https://shopify.dev/docs/api/app-home/web-components/layout-and-structure/page) `aside` slot for a page-level sidebar, [`s-grid`](https://shopify.dev/docs/api/app-home/web-components/layout-and-structure/grid) for column layouts inside content, and [`s-stack`](https://shopify.dev/docs/api/app-home/web-components/layout-and-structure/stack) for one-dimensional flow.

***

## Migration example

This example migrates `Layout.Section variant="oneThird"` to the `s-page` `aside` slot. Keep the primary task in the default page slot, and move supporting content to the aside.

## Migrating a page with an aside

##### Polaris web components

```tsx
export function ProductPage() {
  return (
    <s-page heading="Product" inlineSize="base">
      <s-section>
        <s-heading>Primary content</s-heading>
        <s-paragraph>Manage the product's settings.</s-paragraph>
      </s-section>

      <s-section slot="aside" heading="Details">
        <s-paragraph>Status, vendor, and organization details.</s-paragraph>
      </s-section>
    </s-page>
  );
}
```

##### Polaris React

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

export function ProductPage() {
  return (
    <Page title="Product">
      <Layout>
        <Layout.Section>
          <Card>Primary content</Card>
        </Layout.Section>
        <Layout.Section variant="oneThird">
          <Card>Details</Card>
        </Layout.Section>
      </Layout>
    </Page>
  );
}
```

***

## Map layout sections

| Polaris React | Polaris web components | Migration notes |
| - | - | - |
| `Layout.Section` | Default `s-page` content | Use for the page's primary task. Compose its internal regions with sections, grids, and stacks. |
| `Layout.Section variant="oneThird"` | `slot="aside"` on a direct child of `s-page` | Use for supporting page-level content. The aside is available when `s-page inlineSize="base"`. |
| Multiple content columns | `s-grid` and `s-grid-item` | Define explicit tracks and spans when every column belongs to the same content region. |
| Vertical section spacing | `s-stack direction="block"` | Use an explicit `gap` instead of relying on `Layout` spacing. |
| `Layout.AnnotatedSection` | `s-grid` with an annotation column and a content column | Keep the heading and description adjacent to the controls they explain. Collapse to one column at narrow container widths. |

Don't place primary controls or required instructions in the `aside` slot. When the one-third column is part of a single form or comparison rather than supporting page content, use `s-grid` so the content remains together.

***

## Migrate an annotated section

Build an annotated section with `s-grid`. Put the annotation first in the DOM, followed by the related controls. Use a container-responsive `gridTemplateColumns` value to switch from one column to a narrow annotation column plus a wider content column.

```tsx
<s-query-container>
  <s-grid
    gridTemplateColumns="@container (inline-size > 600px) minmax(12rem, 1fr) minmax(0, 2fr), 1fr"
    gap="large"
  >
    <s-stack gap="small">
      <s-heading>Product organization</s-heading>
      <s-paragraph color="subdued">
        Add details that help merchants find this product.
      </s-paragraph>
    </s-stack>


    <s-stack gap="base">
      <s-text-field label="Product type" name="productType" />
      <s-text-field label="Vendor" name="vendor" />
    </s-stack>
  </s-grid>
</s-query-container>
```

Preserve the annotation heading, description, action, and help links. If the old section contains validation, then keep the error next to the field instead of moving it into the annotation column.

***

## Test and remove Polaris React

* Verify the primary content remains first in reading and focus order.
* Test the `s-page` aside at supported container widths and confirm that no required task content becomes secondary.
* Test annotated sections with long labels, translated text, validation errors, and browser zoom.
* Remove `Layout`, `Layout.Section`, and `Layout.AnnotatedSection` only after every call site uses the intended page region or content composition.

***

## Related guidance

* [Page component](https://shopify.dev/docs/api/app-home/web-components/layout-and-structure/page)
* [Grid component](https://shopify.dev/docs/api/app-home/web-components/layout-and-structure/grid)

***