Upgrading to 2026-01

As of 2025-10, checkout UI extensions use Polaris web components. If you are upgrading from a version earlier than 2025-10, this guide describes how to upgrade your checkout UI extension to the latest version and adopt Polaris web components.

Choose a version:

Anchor to File size limitFile 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. Learn how to analyze your bundle size.

Anchor to Update API versionUpdate API version

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

Anchor to Adjust package dependenciesAdjust 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

Anchor to TypeScript ConfigurationTypeScript 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

Anchor to Upgrade the Shopifiy CLIUpgrade the Shopifiy CLI

The new CLI adds supoort for building 2026-01 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.

Anchor to Optional ESLint configurationOptional ESLint configuration

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

Anchor to Migrate API callsMigrate 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

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

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 (

Include a complimentary gift

</Checkbox>

);

}

Previous API calls in JavaScript

JavaScript

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',

);

Anchor to Migrate hooksMigrate 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

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

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>

);

}

Anchor to Migrate to Polaris web componentsMigrate 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

/* 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

import {

reactExtension,

InlineStack,

TextField,

Button,

} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(

'purchase.checkout.block.render',

() => <Extension />,

);

function Extension() {

return (

</InlineStack>

);

}

Previous components in JavaScript

JavaScript

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'),

]),

);

Anchor to Mapping legacy components to Polaris web componentsMapping legacy components to Polaris web components

Legacy Component	Polaris Web Component	Migration Notes
	Abbreviation	Available
`Badge`	Badge	Available
`Banner`	Banner	Available
`BlockLayout`		Removed. Use `Grid`
`BlockSpacer`		Removed. Use Stack with `gap` property
`BlockStack`		Removed. Use Stack with `direction=block`
`Button`	Button	Available
`Chat`	`Chat`	Coming soon
`Checkbox`	Checkbox	Available
`Choice`	Choice	Available
`ChoiceList`	ChoiceList	Available
`ClipboardItem`	ClipboardItem	Available
`ConsentCheckbox`	ConsentCheckbox	Available
`ConsentPhoneField`	ConsentPhoneField	Available
`DateField`	DateField	Available
`DatePicker`	DatePicker	Available
`Disclosure`	Details and Summary	Available
`Divider`	Divider	Available
`DropZone`	DropZone	Available
	EmailField	Available
`Form`	Form	Available
`Grid`	Grid	Available
`GridItem`	GridItem	Available
`Heading`	Heading	Available
`HeadingGroup`	Section	Available
`Icon`	Icon	Available
`Image`	Image	Available
`InlineLayout`		Removed. Use `Grid`
`InlineSpacer`		Removed. Use Stack
`InlineStack`	Stack	Removed. Use Stack with `direction=inline`
`Link`	Link	Available
`List`	UnorderedList or OrderedList	Available
`ListItem`	ListItem	Available
`Map`	Map	Available
`MapMarker`	MapMarker	Available
`MapPopover`	Popover	Available
`Modal`	Modal	Available
	MoneyField	Available
`PaymentIcon`	PaymentIcon	Available
`PhoneField`	PhoneField	Available
`Popover`	Popover	Available
`Pressable`	Clickable	Available
`ProductThumbnail`	ProductThumbnail	Available
`Progress`	Progress	Available
`QRCode`	QRCode	Available
`ScrollView`	ScrollBox	Available
`Select`	Select	Available
`Sheet`	Sheet	Available
`SkeletonImage`		Removed
`SkeletonText`	SkeletonParagraph	Available
`SkeletonTextBlock`	SkeletonParagraph	Available
`Spinner`	Spinner	Available
`Stepper`	NumberField	Available
`Switch`	Switch	Available
`Tag`	Chip and ClickableChip	Available
`Text`	Text	Available
`TextField` with `multiline`	TextArea	Available
`TextBlock`	Paragraph	Available
`TextField`	TextField	Available
	Time	Available
`ToggleButton`	PressButton	Available
`ToggleButtonGroup`	ChoiceList or PressButton	Available
`Tooltip`	Tooltip	Available
`View`	Box	Available

Was this page helpful?