Migrate Layout from Polaris React

Replace Polaris React Layout with the s-page aside slot for a page-level sidebar, s-grid for column layouts inside content, and s-stack for one-dimensional flow.

Anchor to Migration exampleMigration 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

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>

);

}

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

export function ProductPage() {

return (

<Layout.Section>

<Card>Primary content</Card>

</Layout.Section>

<Layout.Section variant="oneThird">

<Card>Details</Card>

</Layout.Section>

</Layout>

</Page>

);

}

Polaris web components

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

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

Preview

Anchor to Map layout sectionsMap 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.

Anchor to Migrate an annotated sectionMigrate 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.

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

Anchor to Test and remove Polaris ReactTest 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.

Anchor to Related guidanceRelated guidance

Was this page helpful?