Upgrading to 2025-10

This guide describes how to upgrade your point-of-sale UI extension to API version 2025-10 and adopt Polaris web components.

Choose a version:

Anchor to update-api-versionUpdate API version

Set the API version to 2025-10 in shopify.extension.toml to use Polaris web components.

Early access preview

We do not recommend migrating your production point-of-sale UI extension to Polaris yet. However, now is a great time to explore this new version and start thinking about what it means for your own extensions.

Shopify.extension.toml

api_version = "2025-10"

[[extensions]]

name = "your-extension"

handle = "your-extension"

type = "ui_extension"

# Contents of your existing file...

Examples

shopify.extension.toml

api_version = "2025-10"

[[extensions]]
name = "your-extension"
handle = "your-extension"
type = "ui_extension"

# Contents of your existing file...

Anchor to adjust-dependenciesAdjust package dependencies

As of 2025-10, Shopify recommends Preact for UI extensions. Update the dependencies in your package.json file and re-install.

Anchor to adjust-package-dependencies-new-dependencies-with-preactNew dependencies with Preact

Anchor to adjust-package-dependencies-previous-dependencies-with-reactPrevious dependencies with React

Anchor to adjust-package-dependencies-previous-dependencies-with-javascriptPrevious dependencies with JavaScript

New dependencies with Preact

package.json

{

"dependencies": {

"preact": "^10.10.x",

"@shopify/ui-extensions": "~2025.10.0-rc"

}

Anchor to make-typescript-adjustmentsMake TypeScript adjustments

These steps make TypeScript aware of the new global shopify object. Skip these steps if your app was not built using TypeScript.

Anchor to make-typescript-adjustments-1.-update-your-extension's-tsconfig.json1. Update your extension's tsconfig.json

Update your extension config at a path like extensions/{extension-name}/tsconfig.json. You do not need to change your app's root tsconfig.json file.

Anchor to make-typescript-adjustments-2.-generate-type-definition-file-to-support-new-global-shopify-object2. Generate type definition file to support new global shopify object

These commands generate a shopify.d.ts file in your extension directory. This imports UI Extension component types and declares the shopify API object for each extension target.

Update your extension's tsconfig.json

{

"compilerOptions": {

"jsx": "react-jsx",

"jsxImportSource": "preact",

"target": "ES2020",

"checkJs": true,

"allowJs": true,

"moduleResolution": "node",

"esModuleInterop": true

}

Examples

Update your extension's tsconfig.json

New tsconfig.json

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "preact",
    "target": "ES2020",
    "checkJs": true,
    "allowJs": true,
    "moduleResolution": "node",
    "esModuleInterop": true
  }
}

Old tsconfig.json

{
  "compilerOptions": {
    "jsx": "react-jsx"
  },
  "include": ["./src"]
}

Anchor to migrate-api-callsMigrate API calls

Instead of accessing APIs from a callback parameter, access them from the global shopify object. Here's an example of migrating API calls.

Anchor to migrate-api-calls-new-api-calls-in-preactNew API calls in Preact

Anchor to migrate-api-calls-previous-api-calls-in-reactPrevious API calls in React

Anchor to migrate-api-calls-previous-api-calls-in-javascriptPrevious API calls in JavaScript

New API calls in Preact

Preact

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

export default function extension() {

render(<Extension />, document.body);

}

function Extension() {

return <s-button onClick={onButtonClick}>Print</s-button>;

}

async function onButtonClick() {

await shopify.print.print('documents/test-print');

console.log('print completed');

}

Examples

New API calls in Preact

Preact

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return <s-button onClick={onButtonClick}>Print</s-button>;
}

async function onButtonClick() {
  await shopify.print.print('documents/test-print');
  console.log('print completed');
}

Anchor to migrate-hooksMigrate hooks

If you had previously been using React hooks, import those same hooks from a new Preact-specific package. Here's an example of migrating hooks.

Anchor to migrate-hooks-new-hooks-in-preactNew hooks in Preact

Anchor to migrate-hooks-previous-hooks-in-reactPrevious hooks in React

New hooks in Preact

Preact

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

import {useState, useEffect} from 'preact/hooks';

export default function extension() {

render(<ConnectivityStatus />, document.body);

}

function ConnectivityStatus() {

const [isConnected, setIsConnected] = useState(

shopify.connectivity.current.value.internetConnected === 'Connected',

);

useEffect(() => {

const unsubscribe = shopify.connectivity.current.subscribe(

(newConnectivity) => {

setIsConnected(newConnectivity.internetConnected === 'Connected');

);

return unsubscribe;

}, []);

return (

<s-text tone={isConnected ? 'success' : 'warning'}>

Status: {isConnected ? 'Online' : 'Offline'}

</s-text>

);

}

Examples

New hooks in Preact

Preact

import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useState, useEffect} from 'preact/hooks';

export default function extension() {
  render(<ConnectivityStatus />, document.body);
}

function ConnectivityStatus() {
  const [isConnected, setIsConnected] = useState(
    shopify.connectivity.current.value.internetConnected === 'Connected',
  );

  useEffect(() => {
    const unsubscribe = shopify.connectivity.current.subscribe(
      (newConnectivity) => {
        setIsConnected(newConnectivity.internetConnected === 'Connected');
      },
    );
    return unsubscribe;
  }, []);

  return (
    <s-text tone={isConnected ? 'success' : 'warning'}>
      Status: {isConnected ? 'Online' : 'Offline'}
    </s-text>
  );
}

Anchor to migrate-to-polaris-web-componentsMigrate to Polaris web components

Polaris web components are exposed as custom HTML elements. Update your React or JavaScript components to custom elements.

Anchor to migrate-to-polaris-web-components-new-components-in-preactNew components in Preact

Anchor to migrate-to-polaris-web-components-previous-components-in-reactPrevious components in React

Anchor to migrate-to-polaris-web-components-previous-components-in-javascriptPrevious components in JavaScript

New components in Preact

Preact

/* eslint-disable react/self-closing-comp */

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

export default function extension() {

render(<Extension />, document.body);

}

function Extension() {

return (

<s-stack direction="inline" gap="base">

<s-text-field label="Gift message"></s-text-field>

<s-button variant="primary">Save</s-button>

</s-stack>

);

}

Examples

New components in Preact

Preact

/* eslint-disable react/self-closing-comp */
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return (
    <s-stack direction="inline" gap="base">
      <s-text-field label="Gift message"></s-text-field>
      <s-button variant="primary">Save</s-button>
    </s-stack>
  );
}

Anchor to polaris-web-componentsPolaris web components

Early access preview

These web components are an early access preview of the Polaris UI framework. We will add more components over time.

Use the comparison table below to see which Polaris web components are available today, which are coming soon, and how they map to legacy components.

Anchor to mapping-legacy-components-to-polaris-web-componentsMapping legacy components to Polaris web components

Legacy Component	Polaris Web Component	Migration Notes
`Badge`	`Badge`	Available
`Banner`	`Banner`	Available
`Box`	`Box`	Available
`Button`	`Button`	Available
`CameraScanner`	`CameraScanner`	Coming soon
`DateField`	`DateField`	Available
`DatePicker`	`DatePicker`	Available
`DatePicker`	`DateSpinner`	Available, Replaces `DatePicker.inputMode="spinner"`
`Dialog`	`Modal`	Available
`EmailField`	`EmailField`	Available
`Heading`	`Heading`	Available
`Icon`	`Icon`	Available, more icons coming soon.
`Image`	`Image`	Available
`List`	VirtualizedList	Coming soon
`Navigator`		Removed.
`NumberField`	`NumberField`	Available
`PinPad`		Coming soon
`POSBlock`	`POSBlock`	Available
`POSBlockRow`		Replaced by `POSBlock`
`POSReceiptBlock`		Replaced by `POSBlock`
`PrintPreview`	`DocumentPreview`	Coming soon
`QRCode`	`QRCode`	Coming soon
`RadioButtonList`	`ChoiceList`	Available
`Screen`	`Page`	Available
`ScrollView`	`ScrollBox`	Available
`SearchBar`	`SearchField`	Available
`Section`	`Section`	Available
`SectionHeader`		Use `Section.heading`
`SegmentedControl`	`Tabs`/`Tab`	Coming soon
`Selectable`	`Clickable`	Available
`Stack`	`Stack`	Available
`Stepper`	`NumberField`	Use `NumberField` with stepper controls
`Text`	`Text`	Available
`TextArea`	`TextArea`	Available
`TextField`	`TextField`	Available
`Tile`	`Tile`	Available
`TimeField`	`TimeField`	Available
`TimePicker`	`TimePicker`	Available