---
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.
source_url:
  html: 'https://shopify.dev/docs/apps/build/pos/upgrading-to-2025-10'
  md: 'https://shopify.dev/docs/apps/build/pos/upgrading-to-2025-10.md'
api_name: pos-ui-extensions
---

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

[]()

***

## Migrate using AI

Migrate your extensions faster by using Shopify's AI Toolkit to automate the bulk of the work:

1. [Follow the instructions](https://shopify.dev/docs/apps/build/ai-toolkit) to install the Shopify AI Toolkit.

2. Ask your preferred AI coding agent to migrate your extension using the Shopify AI Toolkit with a prompt such as: “Use the shopify polaris pos ui extensions skill to migrate the `extensions/$extensionFolder` extension to version 2025-10”.

   **Info:**

   This process can take several minutes, depending on the size of your extension.

3. Review changes made by your agent before you publish your new extension version:

   * Use the migration guide on this page to be sure your agent covered everything.
   * Run your extension locally to properly test the migrated output and identify any gaps.

***

## Update API version

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

### shopify.​extension.​toml

```toml
api_version = "2025-10"


[[extensions]]
name = "your-extension"
handle = "your-extension"
type = "ui_extension"
uid = "ab22fe63-a741-cbc6-90c1-fbcf94a84426b9cbbe1f"


# 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

##### 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 Java​Script

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

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

***

## Upgrade the Shopify CLI

The new CLI adds support 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

```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 API calls.

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

### Previous API calls in React

##### React

```tsx
import {
  reactExtension,
  Button,
  useApi,
} from '@shopify/ui-extensions-react/point-of-sale';


export default reactExtension('pos.home.modal.render', () => <Extension />);


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


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


  return <Button onPress={onButtonClick} title="Print" />;
}
```

### Previous API calls in Java​Script

##### Java​Script

```ts
import {extension, Button} from '@shopify/ui-extensions/point-of-sale';


export default extension('pos.home.modal.render', (root, api) => {
  async function onButtonClick() {
    await api.print.print('documents/test-print');
    console.log('print completed');
  }


  root.replaceChildren(
    root.createComponent(Button, {
      onPress: onButtonClick,
      title: 'Print',
    }),
  );
});
```

***

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

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

### Previous hooks in React

```tsx
import React from 'react';
import {
  Text,
  useConnectivitySubscription,
  reactExtension,
} from '@shopify/ui-extensions-react/point-of-sale';


const ConnectivityStatus = () => {
  const connectivity = useConnectivitySubscription();
  const isConnected = connectivity.internetConnected === 'Connected';


  return (
    <Text color={isConnected ? 'TextSuccess' : 'TextWarning'}>
      Status: {isConnected ? 'Online' : 'Offline'}
    </Text>
  );
};


export default reactExtension('pos.home.modal.render', () => (
  <ConnectivityStatus />
));
```

***

## Migrate to web components

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

### New components in 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

```tsx
import {
  reactExtension,
  Stack,
  TextField,
  Button,
} from '@shopify/ui-extensions-react/point-of-sale';


export default reactExtension('pos.home.modal.render', () => <Extension />);


function Extension() {
  return (
    <Stack direction="inline" gap="200">
      <TextField label="Gift message" />
      <Button title="Save" variant="primary" />
    </Stack>
  );
}
```

### Previous components in Java​Script

```ts
import {
  extension,
  Stack,
  TextField,
  Button,
} from '@shopify/ui-extensions/point-of-sale';


export default extension('pos.home.modal.render', (root, _api) => {
  root.replaceChildren(
    root.createComponent(Stack, {direction: 'inline', gap: '200'}, [
      root.createComponent(TextField, {
        label: 'Gift message',
      }),
      root.createComponent(Button, {title: 'Save', variant: 'primary'}),
    ]),
  );
});
```

***

## Web components mapping

| **Legacy Component** | **Polaris Web Component** | **Migration Notes** |
| - | - | - |
| `Badge` | [`Badge`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/web-components/feedback-and-status-indicators/badge) | Available |
| `Banner` | [`Banner`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/web-components/feedback-and-status-indicators/banner) | Available |
| `Box` | [`Box`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/web-components/layout-and-structure/box) | Available |
| `Button` | [`Button`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/web-components/actions/button) | Available |
| `CameraScanner` | `ScannerAPI` | Available in 2026-01 |
| `DateField` | [`Date field`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/web-components/forms/date-field) | Available |
| `DatePicker` | [`Date picker`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/web-components/forms/date-picker) | Available |
| `DatePicker` | [`Date spinner`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/web-components/forms/date-spinner) | Available, Replaces `DatePicker.inputMode="spinner"` |
| `Dialog` | [`Modal`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/web-components/feedback-and-status-indicators/modal) | Available |
| `EmailField` | [`Email field`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/web-components/forms/email-field) | Available |
| `Heading` | [`Heading`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/web-components/layout-and-structure/heading) | Available |
| `Icon` | [`Icon`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/web-components/media-and-visuals/icon) | Available, more icons coming soon. |
| `Image` | [`Image`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/web-components/media-and-visuals/image) | Available |
| `List` | `POS list` | Available in 2026-10 |
| `Navigator` | | Removed. |
| `NumberField` | [`Number field`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/web-components/forms/number-field) | Available |
| `PinPad` | `PinPadAPI` | Available |
| `POSBlock` | [`POS block`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/web-components/layout-and-structure/pos-block) | Available |
| `POSBlockRow` | | Replaced by `POS block` |
| `PrintPreview` | `Embed` | Available in 2026-01 |
| `RadioButtonList` | [`Choice list`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/web-components/forms/choice-list) | Available |
| `Screen` | [`Page`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/web-components/layout-and-structure/page) | Available |
| `ScrollView` | [`Scroll box`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/web-components/layout-and-structure/scroll-box) | Available |
| `SearchBar` | [`Search field`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/web-components/forms/search-field) | Available |
| `Section` | [`Section`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/web-components/layout-and-structure/section) | Available |
| `SectionHeader` | | Use `Section.heading` |
| `SegmentedControl` | `Tabs`/`Tab` | Available in 2026-01 |
| `Selectable` | [`Clickable`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/web-components/actions/clickable) | Available |
| `Stack` | [`Stack`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/web-components/layout-and-structure/stack) | Available |
| `Stepper` | [`Number field`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/web-components/forms/number-field) | Use `Number field` with stepper controls |
| `Text` | [`Text`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/web-components/layout-and-structure/text) | Available |
| `TextArea` | [`Text area`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/web-components/forms/text-area) | Available |
| `TextField` | [`Text field`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/web-components/forms/text-field) | Available |
| `Tile` | [`Tile`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/web-components/actions/tile) | Available |
| `TimeField` | [`Time field`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/web-components/forms/time-field) | Available |
| `TimePicker` | [`Time picker`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/web-components/forms/time-picker) | Available |

***