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.

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",

"@preact/signals": "^2.3.x",

"@shopify/ui-extensions": "2025.10.x"

}

Anchor to update-typescript-configurationTypeScript Configuration

Get full IntelliSense and auto-complete support by adding a config file for your extension at extensions/{extension-name}/tsconfig.json. You do not need to change your app's root tsconfig.json file.

Anchor to typescript-configuration-new-tsconfig.jsonNew tsconfig.json

Anchor to typescript-configuration-old-tsconfig.jsonOld tsconfig.json

New tsconfig.json

tsconfig.json

{

"compilerOptions": {

"jsx": "react-jsx",

"jsxImportSource": "preact",

"target": "ES2020",

"checkJs": true,

"allowJs": true,

"moduleResolution": "node",

"esModuleInterop": true

"include": ["./src", "./shopify.d.ts"]

}

Examples

New tsconfig.json

tsconfig.json

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "preact",
    "target": "ES2020",
    "checkJs": true,
    "allowJs": true,
    "moduleResolution": "node",
    "esModuleInterop": true
  },
  "include": ["./src", "./shopify.d.ts"]
}

Anchor to upgrading-shopify-cliUpgrade the Shopifiy CLI

The new CLI adds supoort for building 2025-10 extensions.

The shopify app dev command runs your app and also generates a shopify.d.ts file in your extension directory, adding support for the new global shopify object.

Support new global shopify object

CLI

# Upgrade to latest version of the CLI

npm install -g @shopify/cli

# Run the app to generate the type definition file

shopify app dev

Anchor to eslint-configurationOptional ESLint configuration

If your app is using ESLint, update your configuration to include the new global shopify object.

.eslintrc.cjs

module.exports = {

globals: {

shopify: 'readonly',

};

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 mapping-legacy-components-to-polaris-web-componentsMapping legacy components to Polaris web components

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

Upgrading to 2025-10

Anchor to update-api-versionUpdate API version

Examples

shopify.extension.toml

shopify.extension.toml

Anchor to adjust-dependenciesAdjust package dependencies

Examples

New dependencies with Preact

package.json

Anchor to update-typescript-configurationTypeScript Configuration

Examples

New tsconfig.json

tsconfig.json

Anchor to upgrading-shopify-cliUpgrade the Shopifiy CLI

Examples

Support new global shopify object

CLI

Anchor to eslint-configurationOptional ESLint configuration

Examples

.eslintrc.cjs

Default

Anchor to migrate-api-callsMigrate API calls

Examples

New API calls in Preact

Preact

Anchor to migrate-hooksMigrate hooks

Examples

New hooks in Preact

Preact

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

Examples

New components in Preact

Preact

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