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

### Examples

* #### shopify.extension.toml

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

### Examples

* #### New dependencies with Preact

  ##### package.json

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

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

### Examples

* #### 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"]
  }
  ```

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

### Examples

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

### Examples

* #### .eslintrc.cjs

  ##### Default

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

### Examples

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

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

### Examples

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

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

### Examples

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

## 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 today |
| `Badge` | [Badge](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/titles-and-text/badge) | Available today |
| `Banner` | [Banner](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/feedback/banner) | Available today |
| `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 today |
| `Chat` | `Chat` | Coming soon |
| `Checkbox` | [Checkbox](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/checkbox) | Available today |
| `Choice` | [Choice](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/choicelist#choice) | Available today |
| `ChoiceList` | [ChoiceList](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/choicelist) | Available today |
| `ClipboardItem` | [ClipboardItem](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/utilities/clipboarditem) | Available today |
| `ConsentCheckbox` | [ConsentCheckbox](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/consentcheckbox) | Available today |
| `ConsentPhoneField` | [ConsentPhoneField](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/consentphonefield) | Available today |
| `DateField` | [DateField](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/datefield) | Available today |
| `DatePicker` | [DatePicker](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/datepicker) | Available today |
| `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 today |
| `Divider` | [Divider](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/structure/divider) | Available today |
| `DropZone` | [DropZone](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/dropzone) | Available today |
| | [EmailField](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/emailfield) | Available today |
| `Form` | [Form](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/form) | Available today |
| `Grid` | [Grid](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/structure/grid) | Available today |
| `GridItem` | [GridItem](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/structure/grid#griditem) | Available today |
| `Heading` | [Heading](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/titles-and-text/heading) | Available today |
| `HeadingGroup` | [Section](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/structure/section) | Available today |
| `Icon` | [Icon](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/media/icon) | Available today |
| `Image` | [Image](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/media/image) | Available today |
| `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) | 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 today |
| `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 today |
| `ListItem` | [ListItem](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/other/listitem) | Available today |
| `Map` | [Map](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/interactive/map) | Available today |
| `MapMarker` | [MapMarker](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/interactive/map#mapmarker) | Available today |
| `MapPopover` | [Popover](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/overlays/popover) | Available today |
| `Modal` | [Modal](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/overlay/modal) | Available today |
| | [MoneyField](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/moneyfield) | Available today |
| `PaymentIcon` | [PaymentIcon](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/media/paymenticon) | Available today |
| `PhoneField` | [PhoneField](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/phonefield) | Available today |
| `Popover` | [Popover](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/overlays/popover) | Available today |
| `Pressable` | [Clickable](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/actions/clickable) | Available today |
| `ProductThumbnail` | [ProductThumbnail](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/media/productthumbnail) | Available today |
| `Progress` | [Progress](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/feedback/progress) | Available today |
| `QRCode` | [QRCode](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/other/qrcode) | Available today |
| `ScrollView` | [ScrollBox](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/structure/scrollbox) | Available today |
| `Select` | [Select](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/select) | Available today |
| `Sheet` | [Sheet](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/overlays/sheet) | Available today |
| `SkeletonImage` | | Removed |
| `SkeletonText` | [SkeletonParagraph](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/feedback/skeletonparagraph) | Available today |
| `SkeletonTextBlock` | [SkeletonParagraph](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/feedback/skeletonparagraph) | Available today |
| `Spinner` | [Spinner](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/feedback/spinner) | Available today |
| `Stepper` | [NumberField](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/numberfield) | Available today |
| `Switch` | [Switch](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/switch) | Available today |
| `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 today |
| `Text` | [Text](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/titles-and-text/text) | Available today |
| `TextField` with `multiline` | [TextArea](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/textarea) | Available today |
| `TextBlock` | [Paragraph](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/titles-and-text/paragraph) | Available today |
| `TextField` | [TextField](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/forms/textfield) | Available today |
| | [Time](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/titles-and-text/time) | Available today |
| `ToggleButton` | [PressButton](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/actions/pressbutton) | Available today |
| `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 today |
| `Tooltip` | [Tooltip](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/overlays/tooltip) | Available today |
| `View` | [Box](https://shopify.dev/docs/api/checkout-ui-extensions/2025-10-rc/polaris-web-components/structure/box) | Available today |