---
title: Upgrading to 2025-10
description: |
  This guide describes how to upgrade your checkout UI extension to API version `2025-10` and adopt [Polaris](/beta/next-gen-dev-platform/polaris) web components.
api_version: 2025-10
api_name: checkout-ui-extensions
source_url:
  html: https://shopify.dev/docs/api/checkout-ui-extensions/latest/upgrading-to-2025-10
  md: https://shopify.dev/docs/api/checkout-ui-extensions/latest/upgrading-to-2025-10.md
---

# Upgrading to 2025-10

This guide describes how to upgrade your checkout UI extension to API version `2025-10` and adopt [Polaris](https://shopify.dev/beta/next-gen-dev-platform/polaris) web components.

***

## Update API version

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

## shopify.extension.toml

```toml
api_version = "2025-10"


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


# Contents of your existing file...
```

***

## Adjust package dependencies

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

New dependencies with Preact

Previous dependencies with React

Previous dependencies with JavaScript

## New dependencies with Preact

## package.json

```json
{
  "dependencies": {
    "preact": "^10.10.x",
    "@preact/signals": "^2.3.x",
    "@shopify/ui-extensions": "2025.10.x"
  }
}
```

## Previous dependencies with React

## package.json

```json
{
  "dependencies": {
    "react": "^18.0.0",
    "@shopify/ui-extensions": "2025.4.x",
    "@shopify/ui-extensions-react": "2025.4.x",
    "react-reconciler": "0.29.0"
  },
  "devDependencies": {
    "@types/react": "^18.0.0"
  }
}
```

## Previous dependencies with JavaScript

## package.json

```json
{
  "dependencies": {
    "@shopify/ui-extensions": "2025.4.x"
  }
}
```

***

## Type​Script 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.

New tsconfig.json

Old tsconfig.json

## New tsconfig.json

## tsconfig.json

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

## Old tsconfig.json

## tsconfig.json

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

***

## Upgrade 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

```bash
# Upgrade to latest version of the CLI
npm install -g @shopify/cli


# Run the app to generate the type definition file
shopify app dev
```

***

## Optional ESLint configuration

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

## .eslintrc.cjs

```js
module.exports = {
  globals: {
    shopify: 'readonly',
  },
};
```

***

## Migrate 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.

New API calls in Preact

Previous API calls in React

Previous API calls in JavaScript

## New API calls in Preact

## Preact

```tsx
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,
  );
}
```

## Previous API calls in React

## React

```tsx
import {
  reactExtension,
  Checkbox,
  useApi,
} from '@shopify/ui-extensions-react/checkout';


export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);


function Extension() {
  const api = useApi();


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


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


  return (
    <Checkbox onChange={onCheckboxChange}>
      Include a complimentary gift
    </Checkbox>
  );
}
```

## Previous API calls in JavaScript

## JavaScript

```ts
import {
  extension,
  Checkbox,
} from '@shopify/ui-extensions/checkout';


export default extension(
  'purchase.checkout.block.render',
  (root, api) => {
    async function onCheckboxChange(isChecked) {
      const result =
        await api.applyAttributeChange({
          type: 'updateAttribute',
          key: 'includeGift',
          value: isChecked ? 'yes' : 'no',
        });


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


    root.replaceChildren(
      root.createComponent(
        Checkbox,
        {
          onChange: onCheckboxChange,
        },
        'Include a complimentary gift',
      ),
    );
  },
);
```

***

## Migrate 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.

New hooks in Preact

Previous hooks in React

## New hooks in Preact

## Preact

```tsx
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,
  );
}
```

## Previous hooks in React

## React

```tsx
import {
  reactExtension,
  Checkbox,
  useAttributeValues,
  useApplyAttributeChange,
} from '@shopify/ui-extensions-react/checkout';


export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);


function Extension() {
  const [includeGift] = useAttributeValues([
    'includeGift',
  ]);
  const applyAttributeChange =
    useApplyAttributeChange();


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


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


  return (
    <Checkbox
      checked={includeGift === 'yes'}
      onChange={onCheckboxChange}
    >
      Include a complimentary gift
    </Checkbox>
  );
}
```

***

## Migrate to Polaris web components

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

New components in Preact

Previous components in React

Previous components in JavaScript

## New components in Preact

## Preact

```tsx
/* 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>
  );
}
```

## Previous components in React

## React

```tsx
import {
  reactExtension,
  InlineStack,
  TextField,
  Button,
} from '@shopify/ui-extensions-react/checkout';


export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);


function Extension() {
  return (
    <InlineStack>
      <TextField label="Gift message" />
      <Button>Save</Button>
    </InlineStack>
  );
}
```

## Previous components in JavaScript

## JavaScript

```ts
import {
  extension,
  InlineStack,
  TextField,
  Button,
} from '@shopify/ui-extensions/checkout';


export default extension(
  'purchase.checkout.block.render',
  (root, _api) => {
    root.replaceChildren(
      root.createComponent(InlineStack, {}, [
        root.createComponent(TextField, {
          label: 'Gift message',
        }),
        root.createComponent(Button, {}, 'Save'),
      ]),
    );
  },
);
```

***

## Mapping legacy components to Polaris web components

| **Legacy Component** | **Polaris Web Component** | **Migration Notes** |
| - | - | - |
| | [Abbreviation](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/titles-and-text/abbreviation) | Available |
| `Badge` | [Badge](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/titles-and-text/badge) | Available |
| `Banner` | [Banner](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/feedback/banner) | Available |
| `BlockLayout` | | Removed. Use `Grid` |
| `BlockSpacer` | | Removed. Use [Stack](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/structure/stack) with `gap` property |
| `BlockStack` | | Removed. Use [Stack](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/structure/stack) with `direction=block` |
| `Button` | [Button](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/actions/button) | Available |
| `Chat` | `Chat` | Coming soon |
| `Checkbox` | [Checkbox](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/checkbox) | Available |
| `Choice` | [Choice](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/choicelist#choice) | Available |
| `ChoiceList` | [ChoiceList](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/choicelist) | Available |
| `ClipboardItem` | [ClipboardItem](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/utilities/clipboarditem) | Available |
| `ConsentCheckbox` | [ConsentCheckbox](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/consentcheckbox) | Available |
| `ConsentPhoneField` | [ConsentPhoneField](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/consentphonefield) | Available |
| `DateField` | [DateField](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/datefield) | Available |
| `DatePicker` | [DatePicker](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/datepicker) | Available |
| `Disclosure` | [Details](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/interactive/details) and [Summary](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/interactive/details#summary) | Available |
| `Divider` | [Divider](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/structure/divider) | Available |
| `DropZone` | [DropZone](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/dropzone) | Available |
| | [EmailField](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/emailfield) | Available |
| `Form` | [Form](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/form) | Available |
| `Grid` | [Grid](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/structure/grid) | Available |
| `GridItem` | [GridItem](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/structure/grid#griditem) | Available |
| `Heading` | [Heading](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/titles-and-text/heading) | Available |
| `HeadingGroup` | [Section](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/structure/section) | Available |
| `Icon` | [Icon](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/media/icon) | Available |
| `Image` | [Image](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/media/image) | Available |
| `InlineLayout` | | Removed. Use `Grid` |
| `InlineSpacer` | | Removed. Use [Stack](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/structure/stack) |
| `InlineStack` | [Stack](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/structure/stack) | Removed. Use [Stack](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/structure/stack) with `direction=inline` |
| `Link` | [Link](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/actions/link) | Available |
| `List` | [UnorderedList](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/other/unorderedlist) or [OrderedList](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/other/orderedlist) | Available |
| `ListItem` | [ListItem](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/other/listitem) | Available |
| `Map` | [Map](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/interactive/map) | Available |
| `MapMarker` | [MapMarker](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/interactive/map#mapmarker) | Available |
| `MapPopover` | [Popover](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/overlays/popover) | Available |
| `Modal` | [Modal](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/overlay/modal) | Available |
| | [MoneyField](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/moneyfield) | Available |
| `PaymentIcon` | [PaymentIcon](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/media/paymenticon) | Available |
| `PhoneField` | [PhoneField](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/phonefield) | Available |
| `Popover` | [Popover](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/overlays/popover) | Available |
| `Pressable` | [Clickable](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/actions/clickable) | Available |
| `ProductThumbnail` | [ProductThumbnail](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/media/productthumbnail) | Available |
| `Progress` | [Progress](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/feedback/progress) | Available |
| `QRCode` | [QRCode](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/other/qrcode) | Available |
| `ScrollView` | [ScrollBox](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/structure/scrollbox) | Available |
| `Select` | [Select](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/select) | Available |
| `Sheet` | [Sheet](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/overlays/sheet) | Available |
| `SkeletonImage` | | Removed |
| `SkeletonText` | [SkeletonParagraph](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/feedback/skeletonparagraph) | Available |
| `SkeletonTextBlock` | [SkeletonParagraph](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/feedback/skeletonparagraph) | Available |
| `Spinner` | [Spinner](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/feedback/spinner) | Available |
| `Stepper` | [NumberField](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/numberfield) | Available |
| `Switch` | [Switch](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/switch) | Available |
| `Tag` | [Chip](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/titles-and-text/chip) and [ClickableChip](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/actions/clickablechip) | Available |
| `Text` | [Text](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/titles-and-text/text) | Available |
| `TextField` with `multiline` | [TextArea](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/textarea) | Available |
| `TextBlock` | [Paragraph](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/titles-and-text/paragraph) | Available |
| `TextField` | [TextField](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/textfield) | Available |
| | [Time](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/titles-and-text/time) | Available |
| `ToggleButton` | [PressButton](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/actions/pressbutton) | Available |
| `ToggleButtonGroup` | [ChoiceList](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/choicelist) or [PressButton](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/actions/pressbutton) | Available |
| `Tooltip` | [Tooltip](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/overlays/tooltip) | Available |
| `View` | [Box](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/structure/box) | Available |

***