Checkout UI extensions

Use checkout extensions to build custom functionality for merchants in the checkout flow. You can customize the product information, shipping, payment, order summary, and Shop Pay steps.

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 an extensionScaffolding an extension

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

WatchGetting started video

Scaffolding

npm init @shopify/app@latest

cd your-app

npm run shopify app generate extension

yarn create @shopify/app

cd your-app

yarn shopify app generate extension

pnpm create @shopify/app

cd your-app

pnpm shopify app generate extension

npm

npm init @shopify/app@latest
cd your-app
npm run shopify app generate extension

yarn

yarn create @shopify/app
cd your-app
yarn shopify app generate extension

pnpm

pnpm create @shopify/app
cd your-app
pnpm shopify app generate extension

Anchor to Extension pointsExtension points

Extension points provide locations where merchants can insert custom content. Static extension points are tied to core checkout features like contact information, shipping methods, and order summary line items. Dynamic extension points can be displayed 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.

Extension UIs are rendered using remote UI, a fast and secure environment for custom (non-DOM) UIs.

OverviewExtension points

Extension points

import {

render,

Banner,

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

render('Checkout::Dynamic::Render', () => (

));

function Extension() {

return <Banner>Your extension</Banner>;

}

import {

extend,

Banner,

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

extend(

'Checkout::Dynamic::Render',

(root, api) => {

const banner = root.createComponent(

Banner,

{},

'Your extension',

);

root.appendChild(banner);

);

React

import {
  render,
  Banner,
} from '@shopify/checkout-ui-extensions-react';

render('Checkout::Dynamic::Render', () => (
  <Extension />
));

function Extension() {
  return <Banner>Your extension</Banner>;
}

JS

import {
  extend,
  Banner,
} from '@shopify/checkout-ui-extensions';

extend(
  'Checkout::Dynamic::Render',
  (root, api) => {
    const banner = root.createComponent(
      Banner,
      {},
      'Your extension',
    );
    root.appendChild(banner);
  },
);

Anchor to Configuration fileConfiguration file

When you create a checkout UI extension, the shopify.ui.extension.toml file is automatically generated in your checkout UI extension directory. It contains the extension's configuration, which includes the extension name, extension points, metafields, capabilities, and settings definition.

Learn moreConfiguration guide

Anchor to Extension APIsExtension APIs

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

Extensions use JavaScript to read and write data and call external services, and natively render UIs built using Shopify's checkout components.

API referenceCheckout extensions API

Extension APIs

import {

render,

useShippingAddress,

Banner,

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

render(

'Checkout::DeliveryAddress::RenderBefore',

() => <Extension />,

);

function Extension() {

const {countryCode} = useShippingAddress();

if (countryCode !== 'CA') {

return (

Sorry, we can only ship to Canada at this

time

</Banner>

);

}

import {

extend,

Banner,

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

extend(

'Checkout::DeliveryAddress::RenderBefore',

(root, api) => {

renderApp(root, api);

api.shippingAddress.subscribe(() =>

renderApp(root, api),

);

function renderApp(root, api) {

const {countryCode} =

api.shippingAddress.current;

// In case of a re-render, remove previous children.

for (const child of root.children) {

root.removeChild(child);

}

if (countryCode !== 'CA') {

const banner = root.createComponent(

Banner,

{},

'Sorry, we can only ship to Canada at this time',

);

root.appendChild(banner);

}

React

import {
  render,
  useShippingAddress,
  Banner,
} from '@shopify/checkout-ui-extensions-react';

render(
  'Checkout::DeliveryAddress::RenderBefore',
  () => <Extension />,
);

function Extension() {
  const {countryCode} = useShippingAddress();

  if (countryCode !== 'CA') {
    return (
      <Banner>
        Sorry, we can only ship to Canada at this
        time
      </Banner>
    );
  }
}

JS

import {
  extend,
  Banner,
} from '@shopify/checkout-ui-extensions';

extend(
  'Checkout::DeliveryAddress::RenderBefore',
  (root, api) => {
    renderApp(root, api);

    api.shippingAddress.subscribe(() =>
      renderApp(root, api),
    );
  },
);

function renderApp(root, api) {
  const {countryCode} =
    api.shippingAddress.current;

  // In case of a re-render, remove previous children.
  for (const child of root.children) {
    root.removeChild(child);
  }

  if (countryCode !== 'CA') {
    const banner = root.createComponent(
      Banner,
      {},
      'Sorry, we can only ship to Canada at this time',
    );
    root.appendChild(banner);
  }
}

Anchor to UI componentsUI components

Checkout UI extensions provide UI components that a rendering extension can use to build an interface. 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

UI components

import {

render,

BlockStack,

InlineStack,

Button,

Image,

Text,

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

render('Checkout::Dynamic::Render', () => (

));

function Extension() {

return (

<Text size="large">Heading</Text>

<Text size="small">Description</Text>

</BlockStack>

<Button

onPress={() => {

console.log('button was pressed');

}}

Button

</Button>

</InlineStack>

);

}

import {

extend,

BlockStack,

Button,

Image,

InlineStack,

Text,

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

extend(

'Checkout::Dynamic::Render',

(root, api) => {

const inlineStack = root.createComponent(

InlineStack,

{},

[

root.createComponent(Image, {

source: '/url/for/image',

}),

root.createComponent(BlockStack, {}, [

root.createComponent(

Text,

{size: 'large'},

'Heading',

root.createComponent(

Text,

{size: 'small'},

'Description',

]),

root.createComponent(

Button,

{

onPress: () => {

console.log('button was pressed');

'Button',

);

root.appendChild(inlineStack);

);

React

import {
  render,
  BlockStack,
  InlineStack,
  Button,
  Image,
  Text,
} from '@shopify/checkout-ui-extensions-react';

render('Checkout::Dynamic::Render', () => (
  <Extension />
));

function Extension() {
  return (
    <InlineStack>
      <Image source="/url/for/image" />
      <BlockStack>
        <Text size="large">Heading</Text>
        <Text size="small">Description</Text>
      </BlockStack>
      <Button
        onPress={() => {
          console.log('button was pressed');
        }}
      >
        Button
      </Button>
    </InlineStack>
  );
}

JS

import {
  extend,
  BlockStack,
  Button,
  Image,
  InlineStack,
  Text,
} from '@shopify/checkout-ui-extensions';

extend(
  'Checkout::Dynamic::Render',
  (root, api) => {
    const inlineStack = root.createComponent(
      InlineStack,
      {},
      [
        root.createComponent(Image, {
          source: '/url/for/image',
        }),
        root.createComponent(BlockStack, {}, [
          root.createComponent(
            Text,
            {size: 'large'},
            'Heading',
          ),
          root.createComponent(
            Text,
            {size: 'small'},
            'Description',
          ),
        ]),
        root.createComponent(
          Button,
          {
            onPress: () => {
              console.log('button was pressed');
            },
          },
          'Button',
        ),
      ],
    );

    root.appendChild(inlineStack);
  },
);

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 as shown in the image in the UI components section above.

Checkout UI extensions don't have access to the DOM and can't return DOM nodes. They can't return `` elements, for example. Building an arbitrary tree of HTML and loading additional scripts using script tags are also not supported.

Learn moreRendering extensions

Learn moreCheckout branding

Anchor to TroubleshootingTroubleshooting

Find an end-to-end guide to testing your extensions in Testing checkout UI extensions.

If you're encountering errors when you run dev for an app that contains checkout UI extensions, follow this troubleshooting guide.

Learn moreTroubleshooting guide

Anchor to ResourcesResources

remote-ui

Learn more about the underlying technology that powers checkout UI extensions.

UX guidelines

Use our UX guidelines when you're designing your checkout experiences to ensure that they're trustworthy, efficient, and considerate.

Localization

You can use JavaScript APIs to access translations and localize UI extensions for international merchants and customers.

Tutorials

Check out our tutorials on how to build payment or delivery customizations, product offers, custom banners and more.

Was this page helpful?