Checkout UI extensions

Checkout UI extensions let app developers build custom functionality that merchants can install at defined points in the checkout flow, including product information, shipping, payment, order summary, and Shop Pay.

Shopify Plus

Checkout UI extensions for the information, shipping and payment step are available only to stores on a Shopify Plus plan.

Choose a version:

Anchor to scaffolding-extensionScaffolding an extension

Use the Shopify CLI to generate a new extension in the directory of your app.

Make sure you’re using Shopify CLI v3.85.3 or higher. You can check your version by running shopify version.

Shopify CLI

# create an app if you don't already have one:

shopify app init --name my-app

# navigate to your app's root directory:

cd my-app

# generate a new extension:

shopify app generate extension

# follow the steps to create a new

# extension in ./extensions.

Examples

Shopify CLI

Default

# create an app if you don't already have one: shopify app init --name my-app # navigate to your app's root directory: cd my-app # generate a new extension: shopify app generate extension # follow the steps to create a new # extension in ./extensions.

Anchor to eslint-configurationOptional ESLint configuration

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

.eslintrc.cjs

module.exports = {

globals: {

shopify: "readonly"

};

Anchor to configuration-fileConfiguration file

When you create a UI extension, the shopify.extension.toml file is generated in your extension directory. Use this file to configure your extension name, extension targets, metafields, capabilities, and settings definition.

Extension targets provide locations where merchants can insert custom content. Static extension targets are tied to core checkout features like contact information, shipping methods, and order summary line items. Block targets can display at any point in the checkout process and will always render regardless of which checkout features are available. An example is a field to capture order notes from the customer.

Learn moreConfiguration guide

OverviewExtension targets

Shopify.extension.toml

api_version = "2025-10"

[[extensions]]

type = "ui_extension"

name = "Your checkout extension"

handle = "checkout-ui"

[[extensions.targeting]]

target = "purchase.checkout.block.render"

module = "./Extension.jsx"

Examples

shopify.extension.toml

Default

api_version = "2025-10" [[extensions]] type = "ui_extension" name = "Your checkout extension" handle = "checkout-ui" [[extensions.targeting]] target = "purchase.checkout.block.render" module = "./Extension.jsx"

Anchor to extension-functionsExtension functions

Checkout will execute the module’s default export so it can render a user interface.

Extension UIs are powered by Remote DOM, a fast and secure environment for custom (non-DOM) UIs.

Extension.jsx

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

export default async () => {

render(<Extension />, document.body);

};

function Extension() {

return <s-banner>Your extension</s-banner>;

}

Examples

Extension.jsx

Default

import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default async () => { render(<Extension />, document.body); }; function Extension() { return <s-banner>Your extension</s-banner>; }

Anchor to preact-by-defaultPreact by default

UI Extensions are scaffolded with Preact by default. This means you can use Preact patterns and principles within your extension.

Since Preact is included as a standard dependency, you have access to all of its features including hooks like useState and useEffect for managing component state and side effects.

You can also use Preact Signals for reactive state management, and take advantage of standard web APIs just like you would in a regular Preact application.

Extension.jsx

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

import {useState} from 'preact/hooks';

export default async () => {

render(<Extension />, document.body);

};

function Extension() {

const [count, setCount] = useState(0);

return (

<s-text>Count: {count}</s-text>

<s-button

onClick={() => setCount(count + 1)}

Increment

</s-button>

</>

);

}

Examples

Extension.jsx

Default

import '@shopify/ui-extensions/preact'; import {render} from 'preact'; import {useState} from 'preact/hooks'; export default async () => { render(<Extension />, document.body); }; function Extension() { const [count, setCount] = useState(0); return ( <> <s-text>Count: {count}</s-text> <s-button onClick={() => setCount(count + 1)} > Increment </s-button> </> ); }

Anchor to extension-apisExtension APIs

The platform defines a global shopify object that contains all properties and methods available to UI extensions.

These APIs enable UI extensions to get information about the checkout or related objects and to perform actions. For example, you can retrieve what’s in customer carts and offer related products.

APIs with a value property are Preact Signals. Preact will automatically re-render your extension as values change.

API referenceCheckout extensions API

Extension.jsx

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

export default async () => {

render(<Extension />, document.body);

};

function Extension() {

if (

shopify.shippingAddress.value?.countryCode !==

'CA'

) {

return (

<s-banner>

Sorry, we can only ship to Canada at this

time

</s-banner>

);

}

Examples

Extension.jsx

Default

import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default async () => { render(<Extension />, document.body); }; function Extension() { if ( shopify.shippingAddress.value?.countryCode !== 'CA' ) { return ( <s-banner> Sorry, we can only ship to Canada at this time </s-banner> ); } }

Anchor to ui-componentsUI components

Checkout UI extensions declare their interface using Polaris web components. Shopify renders the UI natively, so it’s performant, accessible, and works in all of checkout’s supported browsers.

Checkout components are designed to be flexible, enabling you to layer and mix them to create highly-customized app extensions that feel seamless within the checkout experience. All components inherit a merchant’s brand settings and the CSS cannot be altered or overridden.

API referenceComponent library

UI ReferenceFigma UI kit

Extension.jsx

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

export default function extension() {

render(<Extension />, document.body);

}

function Extension() {

return (

<s-stack direction="inline">

<s-image src="https://cdn.shopify.com/YOUR_IMAGE_HERE" />

<s-stack>

<s-heading>Heading</s-heading>

<s-text type="small">Description</s-text>

</s-stack>

<s-button

onClick={() => {

console.log('button was pressed');

}}

Button

</s-button>

</s-stack>

);

}

Examples

Extension.jsx

Default

import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default function extension() { render(<Extension />, document.body); } function Extension() { return ( <s-stack direction="inline"> <s-image src="https://cdn.shopify.com/YOUR_IMAGE_HERE" /> <s-stack> <s-heading>Heading</s-heading> <s-text type="small">Description</s-text> </s-stack> <s-button onClick={() => { console.log('button was pressed'); }} > Button </s-button> </s-stack> ); }

Anchor to securitySecurity

Checkout UI extensions are a safe and secure way to customize the appearance and functionality of the checkout page without compromising the security of checkout or customer data.

They run in an isolated sandbox, separate from the checkout page and other UI extensions.
They don't have access to sensitive payment information or the checkout page itself (HTML or other assets).
They are limited to specific UI components and APIs that are exposed by the platform.
They have limited access to global web APIs.
Apps that wish to access protected customer data, must submit an application and are subject to strict security guidelines and review proccesses by Shopify.

Constraints

You can’t override the CSS for UI components. The checkout UI will always render the merchant’s own branding.

Checkout UI extensions don’t have access to the real checkout DOM and can’t render arbitrary HTML such as <div> elements or <script> tags, etc. They can only render custom HTML elements provided by Shopify.