---
title: Upgrading to 2026-01
description: >
  As of `2025-10`, customer account UI extensions use [Polaris web
  components](./polaris-web-components). If you are upgrading from a version
  earlier than `2025-10`, this guide describes how to upgrade your customer
  account UI extension to the latest version and adopt Polaris web components.
api_version: 2026-01
api_name: customer-account-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/latest/upgrading-to-2026-01
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/latest/upgrading-to-2026-01.md
---

# Upgrading to 2026-01

As of `2025-10`, customer account UI extensions use [Polaris web components](./polaris-web-components). If you are upgrading from a version earlier than `2025-10`, this guide describes how to upgrade your customer account UI extension to the latest version and adopt Polaris web components.

***

## File size limit

**Info:**

Your compiled UI extension bundle can't exceed 64 KB. Shopify enforces this limit at deployment to ensure fast loading times and optimal performance.

***

## Update API version

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

## shopify.extension.toml

```toml
api_version = "2026-01"


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


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

***

## Adjust package dependencies

As of `2026-01`, 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": "2026.01.x"
  }
}
```

## Previous dependencies with React

## package.json

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

## Previous dependencies with JavaScript

## package.json

```json
{
  "dependencies": {
    "@shopify/ui-extensions": "2026.01.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 don't 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
  }
}
```

## Old tsconfig.json

## tsconfig.json

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

***

## Upgrade the Shopifiy CLI

The new CLI adds support for building 2026-01 extensions.

The [`shopify app dev`](https://shopify.dev/docs/api/shopify-cli/app/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 or React hook, access them from the global `shopify` object. Here's an example of migrating the [Cart Line Target API](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/targets/order-status/customer-account-order-status-cart-line-item-render-after) 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-text>Line item title: {shopify.target.value.merchandise.title}</s-text>
  );
}
```

## Previous API calls in React

## React

```tsx
import {
  reactExtension,
  Text,
  useCartLineTarget,
} from '@shopify/ui-extensions-react/customer-account';


export default reactExtension(
  'customer-account.order-status.cart-line-item.render-after',
  () => <Extension />,
);


function Extension() {
  const {
    merchandise: {title},
  } = useCartLineTarget();


  return <Text>Line item title: {title}</Text>;
}
```

## Previous API calls in JavaScript

## JavaScript

```tsx
import {extension} from '@shopify/ui-extensions/customer-account';


export default extension(
  'customer-account.order-status.cart-line-item.render-after',
  (root, {target}) => {
    const text = root.createText(`Line item title: ${target.current.title}`);
    root.appendChild(text);


    target.subscribe((updatedTarget) => {
      text.updateText(`Line item title: ${updatedTarget.title}`);
    });
  },
);
```

***

## 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
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/customer-account';


export default reactExtension(
  'customer-account.order-status.block.render',
  () => <Extension />,
);


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

## Previous components in JavaScript

## JavaScript

```tsx
import {
  extension,
  InlineStack,
  TextField,
  Button,
} from '@shopify/ui-extensions/customer-account';


export default extension(
  'customer-account.order-status.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

| **Legacy component** | **Polaris web component** | **Migration notes** |
| - | - | - |
| `Avatar` | [`Avatar`](https://shopify.dev/api/customer-account-ui-extensions/polaris-web-components/media/avatar) | Available today |
| | [`ButtonGroup`](https://shopify.dev/api/customer-account-ui-extensions/polaris-web-components/actions/buttongroup) | Available today |
| `Card` | [`Section`](https://shopify.dev/api/customer-account-ui-extensions/polaris-web-components/structure/section) | Available today |
| `CustomerAccountAction` | [`CustomerAccountAction`](https://shopify.dev/api/customer-account-ui-extensions/polaris-web-components/actions/customeraccountaction) | Available today |
| `ImageGroup` | [`ImageGroup`](https://shopify.dev/api/customer-account-ui-extensions/polaris-web-components/media/imagegroup) | Available today |
| `Menu` | [`Menu`](https://shopify.dev/api/customer-account-ui-extensions/polaris-web-components/actions/menu) | Available today |
| `Page` | [`Page`](https://shopify.dev/api/customer-account-ui-extensions/polaris-web-components/structure/page) | Available today |
| `ResourceItem` | | Removed. Use [`Section`](https://shopify.dev/api/customer-account-ui-extensions/polaris-web-components/structure/section) instead. |

***

## Additional components

In addition to the components above, you can also use Polaris web components in the checkout library to build customer account UI extensions.

[More Polaris web components - Checkout components](https://shopify.dev/docs/api/checkout-ui-extensions/polaris-web-components)

***