Migrate Breadcrumbs from Polaris React

Polaris web components don't provide a standalone Breadcrumbs component. Place s-link children in the s-page breadcrumb-actions slot.

The Polaris React Breadcrumbs component from @shopify/polaris rendered one icon-only back action despite its plural name. The page slot can show the parent hierarchy with visible link labels and owns the breadcrumb presentation.

Anchor to Migrate the page and breadcrumb togetherMigrate the page and breadcrumb together

Most apps use the old breadcrumb through the Polaris React Page backAction property. Move the action into the destination page rather than rendering a breadcrumb as ordinary page content.

export function EditProductPage() {
  return (
    <s-page heading="Edit product">
      <s-link slot="breadcrumb-actions" href="/products">
        Products
      </s-link>
      <s-section heading="Product details">
        <s-text>Update product information and availability.</s-text>
      </s-section>
    </s-page>
  );
}

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

export function EditProductPage() {
  return (
    <Page
      title="Edit product"
      backAction={{
        content: 'Products',
        url: '/products',
      }}
    >
      <Card>
        <Text as="h2" variant="headingSm">Product details</Text>
        <Text as="p">Update product information and availability.</Text>
      </Card>
    </Page>
  );
}

Anchor to Replace backActionReplace backAction

Replace the backAction descriptor object with a slotted component. Prefer a link when the parent has a URL.

Polaris React used content as the icon-only button's fallback accessible label. In the new slot, write a concise visible parent label such as Products or Settings. Don't use Back as the only text because it doesn't describe the destination.

Anchor to Link actionsLink actions

Use s-link for hierarchy navigation. Set slot="breadcrumb-actions", move url to href, and use the parent name as the visible child text. This gives merchants a stable destination and preserves expected link behavior such as opening in a new tab.

Anchor to Callback actionsCallback actions

The breadcrumb-actions slot accepts links, not buttons. If the old callback only calls history.back(), replace it with the parent URL. Breadcrumbs represent hierarchy, not the merchant's browser history.

If the callback guards unsaved changes, call shopify.saveBar.leaveConfirmation() before navigating. Continue to the real parent href only when the promise resolves. Move callbacks that perform non-navigation actions into a supported page action slot.

Anchor to Add multiple parent levelsAdd multiple parent levels

You can add more than one slotted s-link when the hierarchy helps merchants understand the current location. Put them in ancestor-to-parent order. Don't add the current page as a breadcrumb; s-page already displays it in heading. Keep the trail short enough to remain useful at narrow iframe widths.

Anchor to Removed component behaviorRemoved component behavior

• Remove the imported ArrowLeftIcon; the page owns breadcrumb presentation.
• Remove pointer-down blur helpers and wrappers that only styled the old icon button.
• Don't render Breadcrumbs outside the page header and manually recreate its spacing.
• Don't keep a backAction compatibility object after all consumers render slotted links.

Anchor to Test the migrationTest the migration

• Follow every breadcrumb and confirm it reaches the intended parent, including routes with nested IDs or query parameters.
• Verify callback breadcrumbs preserve unsaved-change prompts and don't run twice.
• Test keyboard focus, visible labels, accessible names, and new-tab behavior.
• Check one-level and multi-level trails at narrow iframe widths.
• Confirm the current page heading isn't duplicated in the breadcrumb trail.
• Remove the Polaris React Breadcrumbs import, or the Page backAction object, after its final consumer is migrated.

Anchor to Related guidanceRelated guidance

• Page component
• Link component
• Migrate Page from Polaris React
• Migrate from Polaris React