Upgrading to 2025-10

This guide describes how to upgrade your checkout 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 checkout 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-update-your-extension's-tsconfig.jsonUpdate 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-generate-type-definition-file-to-support-new-global-shopify-objectGenerate type definition file to support new global shopify object

These commands generate a shopify.d.ts file in your extension directory.

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 the applyAttributeChange API call.

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

onChange={onCheckboxChange}

label="Include a complimentary gift"

);

}

async function onCheckboxChange(event) {

const isChecked = event.target.checked;

const result =

await shopify.applyAttributeChange({

type: 'updateAttribute',

key: 'includeGift',

value: isChecked ? 'yes' : 'no',

});

console.log(

'applyAttributeChange result',

result,

);

}

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-checkbox
      onChange={onCheckboxChange}
      label="Include a complimentary gift"
    />
  );
}

async function onCheckboxChange(event) {
  const isChecked = event.target.checked;

  const result =
    await shopify.applyAttributeChange({
      type: 'updateAttribute',
      key: 'includeGift',
      value: isChecked ? 'yes' : 'no',
    });

  console.log(
    'applyAttributeChange result',
    result,
  );
}

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 the useAttributeValues hook.

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 {useAttributeValues} from '@shopify/ui-extensions/checkout/preact';

export default function extension() {

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

}

function Extension() {

const [includeGift] = useAttributeValues([

'includeGift',

]);

return (

<s-checkbox

checked={includeGift === 'yes'}

onChange={onCheckboxChange}

label="Include a complimentary gift"

);

}

async function onCheckboxChange(event) {

const isChecked = event.target.checked;

const result =

await shopify.applyAttributeChange({

type: 'updateAttribute',

key: 'includeGift',

value: isChecked ? 'yes' : 'no',

});

console.log(

'applyAttributeChange result',

result,

);

}

examples

New hooks in Preact

Preact

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

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

function Extension() {
  const [includeGift] = useAttributeValues([
    'includeGift',
  ]);
  return (
    <s-checkbox
      checked={includeGift === 'yes'}
      onChange={onCheckboxChange}
      label="Include a complimentary gift"
    />
  );
}

async function onCheckboxChange(event) {
  const isChecked = event.target.checked;

  const result =
    await shopify.applyAttributeChange({
      type: 'updateAttribute',
      key: 'includeGift',
      value: isChecked ? 'yes' : 'no',
    });

  console.log(
    'applyAttributeChange result',
    result,
  );
}

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
	Abbreviation	Available today
`Badge`	`Badge`	Coming soon
`Banner`	Banner	Available today
`BlockLayout`		Removed. Use `Grid`
`BlockSpacer`		Removed. Use Stack with `gap` property
`BlockStack`		Removed. Use Stack with `direction=block`
`Button`	Button	Available today
`Chat`	`Chat`	Coming soon
`Checkbox`	Checkbox	Available today
`Choice`	`Choice`	Coming soon
`ChoiceList`	`ChoiceList`	Coming soon
`ClipboardItem`	ClipboardItem	Available today
`ConsentCheckbox`	`ConsentCheckbox`	Coming soon
`ConsentPhoneField`	`ConsentPhoneField`	Coming soon
`DateField`	`DateField`	Coming soon
`DatePicker`	`DatePicker`	Coming soon
`Disclosure`	`Details` and `Summary`	Coming soon
`Divider`	`Divider`	Coming soon
`DropZone`	DropZone	Available today
`EmailField`	EmailField	Available today
`Form`	Form	Available today
`Grid`	`Grid`	Coming soon
`GridItem`	`GridItem`	Coming soon
`Heading`	Heading	Available today
`HeadingGroup`	Section	Available today
`Icon`	Icon	Available today
`Image`	Image	Available today
`InlineLayout`		Removed. Use `Grid`
`InlineSpacer`		Removed. Use Stack
`InlineStack`	`Stack`	Use Stack with `direction=inline`
`Link`	Link	Available today
`List`	UnorderedList or OrderedList	Available today
`ListItem`	ListItem	Available today
`Map`	Map	Available today
`MapMarker`	MapMarker	Available today
`MapPopover`	`Popover`	Coming soon
`Modal`	Modal	Available today
`PaymentIcon`	`PaymentIcon`	Coming soon
`PhoneField`	PhoneField	Available today
`Popover`	`Popover`	Coming soon
`Pressable`	`Clickable`	Coming soon
`ProductThumbnail`	ProductThumbnail	Available today
`Progress`	Progress	Available today
`QRCode`	`QRCode`	Available today
`ScrollView`	`ScrollBox`	Coming soon
`Select`	`Select`	Coming soon
`Sheet`	`Sheet`	Coming soon
`SkeletonImage`		Removed
`SkeletonText`	`SkeletonText`	Coming soon
`SkeletonTextBlock`	`SkeletonTextBlock`	Coming soon
`Spinner`	Spinner	Available today
`Stepper`	`NumberField`	Coming soon
`Switch`	`Switch`	Coming soon
`Tag`	`Tag`	Coming soon
`Text`	Text	Available today
`TextArea`	TextArea	Available today
`TextBlock`	Paragraph	Available today
`TextField`	TextField	Available today
	Time	Available today
`ToggleButton`	TBD	Coming soon
`ToggleButtonGroup`	TBD	Coming soon
`Tooltip`	`Tooltip`	Coming soon
`View`	Box	Available today