Checkout UI / Customer Account UI / Migration

Polaris web components migration guide published
The official guide for upgrading Checkout & Customer Account UI extensions to the new API

From the legacy React/JavaScript API to Preact + Polaris web components + global shopify object. Published together with 60+ per-component pages and the checkout → cart metafield migration steps.

What's on this page
  1. What was actually published (understand in 30 seconds)
  2. The big picture of the migration (Before → After diagram)
  3. What's inside the 3 published guides
  4. Target extensions and API versions
  5. The migration workflow (4 steps)
  6. 5 key points for developers
  7. 3 use cases you can apply to your work
  8. A one-line summary you can use in a pitch

1What was actually published

Checkout UI extensions / Customer Account UI extensions,from the React/JavaScript API to Preact + Polaris web components + global shopify objecta new official migration guide for rewriting them has been published.

① Overall migration guide

From the React/JS extension API to Preact / Polaris web components / global shopify the steps for rewriting them to use the object.

60+

② 60+ per-component pages

Button / Checkbox / TextField / Banner / View, and more — migration steps broken out into individual pages per component.

③ Metafield migration steps

The migration steps from checkout metafields → cart metafields were published at the same time.

2The big picture of the migration (Before → After diagram)

Before: API 2025-07 and earlier React / JavaScript Extension API @shopify/ui-extensions-react Custom React components checkout metafields More code / larger bundles migration guides published After: API 2025-10 and later (default) Preact + Polaris web components global shopify object <s-button> <s-text-field> <s-banner> ... cart metafields Polaris standard UI / applied by default
Polaris web components : A Web Components–based UI library provided by Shopify. Framework-agnostic and React-independent, it forms the foundation of a new extension model that runs on Preact + a global shopify object.
The default from API 2025-10 onward— since it is built in this way, extensions using earlier versions are subject to migration.

3What's in the three published guides

GuideContentWork involved
Overall migration guide Steps for migrating from the React/JavaScript extension API to Preact + Polaris web components + global shopify object Overall strategy Architecture overhaul
Per-component pages (60+) Old→new mappings per component, such as Button/Checkbox/TextField/Banner/View Per component Individual rewrites
Metafield migration Steps for migrating from checkout metafields to cart metafields Data layer Schema migration
Checkout UI extensions migration guide Entry-point page focused on Checkout UI extensions Entry point Recommended starting point
Customer Account UI extensions migration guide Entry-point page focused on Customer Account UI extensions Entry point Recommended starting point

4Target extensions and API versions

Checkout UI extensions

An extension for inserting custom UI into the checkout screen. The main focus of this migration guide.

Customer Account UI extensions

An extension for inserting custom UI into the customer account page. In scope as well, just like Checkout.

Extensions using an API version earlier than 2025-10 are subject to migration. Polaris web components are the default from 2025-10 onward, and existing implementations running on older versions need to be upgraded following the guide.

5The migration workflow (4 steps)

1

Open the entry-point guide

Start from the Checkout or Customer Account migration guide.

2
React→Preact

Revamp the foundation

From React/JS to Preact + global shopify Rewrite to.

3
60+

Component replacement

Replace Button/TextField/Banner and the like, following the individual Polaris WC pages.

4

Metafield migration

Replace checkout metafields with cart metafields.

This article does not cover the parallel release strategy or deprecation deadlines for breaking changes. See each migration guide for details.

6Five key points for developers

2025-10

1. The watershed is API 2025-10

Polaris web components become the default in 2025-10. It is explicitly stated that extensions using anything earlier fall under this guide.

React Preact

2. Switching from React to Preact

The UI framework is unified on Preact + Polaris web components. React-specific hooks ecosystems and HOCs cannot be carried over as-is.

shopify

3. Global shopify object

Access to the extension API is consolidated through the global shopify object. The way values that were previously obtained via React Hooks are accessed changes here.

60+

4. More than 60 per-component pages

Because individual pages are provided for each component—Button/Checkbox/TextField/Banner/View, and so on—reconciling and resolving the differences one at a timeis the realistic approach.

checkout cart

5. Checkout metafields → cart metafields

In parallel with the UI-layer overhaul, where the data lives also shifts: checkout metafields → cart metafields. Because the storage location for custom data that was held only during checkout changes, you need to identify every read/write reference.

7Three practical use cases

2025-07 2025-10+
USE CASE 1

Turning an API version upgrade of an existing Checkout UI extension into a project

Challenge
A Checkout UI extension in production has been left on API 2025-07 or earlier, with an old React/JS-based implementation still in place.
Approach
Use the official Checkout UI extensions migration guide as the starting point, and rewrite to Preact + Polaris web components + the global shopify object, carried out in stages.
Impact
You can keep pace with the standard Polaris UI / future feature additions become easier to put on the official roadmap.
Technical note
Using the 60+ per-component pages, the realistic approach is to adopt a review workflow that resolves diffs component by component.
Polaris WC
USE CASE 2

Aligning the custom UI of the Customer Account page with the new foundation

Challenge
Features are built on the customer account page using custom React components, but the UI tone and implementation foundation are out of sync with the Checkout side.
Approach
Following the Customer Account UI extensions migration guide, lean toward Polaris web components and unify on the same Preact + shopify configuration as on the Checkout side.
Impact
The UI's look and behavior align with the Polaris standard, reducing the burden of maintaining custom styles.
Technical notes
Since Checkout and Customer Account can share the same Polaris WC components (Button, Banner, View, etc.), this works well with a shared-module approach.
checkout metafield cart metafield
USE CASE 3

Inventory the checkout metafield dependencies and migrate them to cart metafields

Challenge
Custom attributes (gift options, shipping options, delivery date/time, etc.) are stored in checkout metafields, so the data layer needs to be reorganized alongside the UI migration.
Approach
Use the official metafield migration guide to list the target namespaces/keys → replace them with cart metafields → and update the reading-side extensions and app-side logic to match.
Impact
The UI overhaul and the data-model cleanup get handled in the same project, simplifying downstream operations.
Technical notes
Unless you also map out the existing data read/write paths (admin app, Functions, external integrations) at the same time, a missed migration can easily leave values showing on only some screens.

8One-line summary you can use in a proposal

"For Checkout / Customer Account UI extensions, Shopify has published a migration guide covering
React/JS → Preact + Polaris web components + the global shopify object—complete with the migration steps.
It includes 60+ per-component pages plus checkout → cart metafield migration steps,
so existing extensions on an API version earlier than 2025-10 need to take action.."