---
title: Upgrading to 2025-10
description: >

  This guide describes how to upgrade your point-of-sale UI extension to API
  version `2025-10` and adopt [Polaris](/beta/next-gen-dev-platform/polaris) web
  components.
api_version: 2025-10
api_name: pos_ui_extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/pos-ui-extensions/2025-10-rc/upgrading-to-2025-10
  md: >-
    https://shopify.dev/docs/api/pos-ui-extensions/2025-10-rc/upgrading-to-2025-10.txt
---

# Upgrading to 2025-10

This guide describes how to upgrade your point-of-sale 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.

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.

### 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",
      "@shopify/ui-extensions": "~2025.10.0-rc"
    }
  }
  ```

## Make TypeScript adjustments

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

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

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

### Examples

* #### Update your extension's tsconfig.json

  ##### New tsconfig.json

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

  ##### Old tsconfig.json

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

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

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-button onClick={onButtonClick}>Print</s-button>;
  }

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

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

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

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

## Polaris web components

Early access preview

These web components are an early access preview of the [Polaris](https://shopify.dev/beta/next-gen-dev-platform/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.

## Mapping legacy components to Polaris web components

| **Legacy Component** | **Polaris Web Component** | **Migration Notes** |
| - | - | - |
| `Badge` | [`Badge`](polaris-web-components/titles-and-text/badge) | Available |
| `Banner` | [`Banner`](polaris-web-components/feedback/banner) | Available |
| `Box` | [`Box`](polaris-web-components/structure/box) | Available |
| `Button` | [`Button`](polaris-web-components/actions/button) | Available |
| `CameraScanner` | `CameraScanner` | Coming soon |
| `DateField` | [`DateField`](polaris-web-components/forms/datefield) | Available |
| `DatePicker` | [`DatePicker`](polaris-web-components/forms/datepicker) | Available |
| `DatePicker` | [`DateSpinner`](polaris-web-components/forms/datespinner) | Available, Replaces `DatePicker.inputMode="spinner"` |
| `Dialog` | [`Modal`](polaris-web-components/structure/modal) | Available |
| `EmailField` | [`EmailField`](polaris-web-components/forms/emailfield) | Available |
| `Heading` | [`Heading`](polaris-web-components/titles-and-text/heading) | Available |
| `Icon` | [`Icon`](polaris-web-components/media/icon) | Available, more icons coming soon. |
| `Image` | [`Image`](polaris-web-components/media/image) | Available |
| `List` | VirtualizedList | Coming soon |
| `Navigator` | | Removed. |
| `NumberField` | [`NumberField`](polaris-web-components/forms/numberfield) | Available |
| `PinPad` | | Coming soon |
| `POSBlock` | [`POSBlock`](polaris-web-components/structure/posblock) | Available |
| `POSBlockRow` | | Replaced by `POSBlock` |
| `POSReceiptBlock` | | Replaced by `POSBlock` |
| `PrintPreview` | `DocumentPreview` | Coming soon |
| `QRCode` | `QRCode` | Coming soon |
| `RadioButtonList` | [`ChoiceList`](polaris-web-components/forms/choicelist) | Available |
| `Screen` | [`Page`](polaris-web-components/structure/page) | Available |
| `ScrollView` | [`ScrollBox`](polaris-web-components/structure/scrollbox) | Available |
| `SearchBar` | [`SearchField`](polaris-web-components/forms/searchfield) | Available |
| `Section` | [`Section`](polaris-web-components/structure/section) | Available |
| `SectionHeader` | | Use `Section.heading` |
| `SegmentedControl` | `Tabs`/`Tab` | Coming soon |
| `Selectable` | [`Clickable`](polaris-web-components/actions/clickable) | Available |
| `Stack` | [`Stack`](polaris-web-components/structure/stack) | Available |
| `Stepper` | [`NumberField`](polaris-web-components/forms/numberfield) | Use `NumberField` with stepper controls |
| `Text` | [`Text`](polaris-web-components/titles-and-text/text) | Available |
| `TextArea` | [`TextArea`](polaris-web-components/forms/textarea) | Available |
| `TextField` | [`TextField`](polaris-web-components/forms/textfield) | Available |
| `Tile` | [`Tile`](polaris-web-components/actions/tile) | Available |
| `TimeField` | [`TimeField`](polaris-web-components/forms/timefield) | Available |
| `TimePicker` | [`TimePicker`](polaris-web-components/forms/timepicker) | Available |