Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Choose a version:

UI API

The API for interacting with the extension’s UI.

Anchor to StandardApiStandardApi

The base API object provided to purchase extension targets.

Anchor to ui ui required: Methods to interact with the extension’s UI.

Ui

overlay
Allows the extension to close an overlay programmatically. Supported overlay components are [Modal](/docs/api/checkout-ui-extensions/unstable/components/overlays/modal), [Sheet](/docs/api/checkout-ui-extensions/unstable/components/overlays/sheet) and [Popover](/docs/api/checkout-ui-extensions/unstable/components/overlays/popover).
```
Overlay
```

Overlay

close
Closes the overlay with the given ID.
```
(overlayId: string) => void
```

Examples

React

import {

reactExtension,

useApi,

Button,

Link,

Modal,

TextBlock,

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

export default reactExtension(

'purchase.checkout.block.render',

() => <Extension />,

);

function Extension() {

const {ui} = useApi();

return (

<Link

overlay={

<Modal

id="my-modal"

padding

title="Return policy"

We have a 30-day return policy.

</TextBlock>

<Button

onPress={() =>

ui.overlay.close('my-modal')

}

</Button>

</Modal>

}

Return policy

</Link>

);

}

Examples

React

import {
  reactExtension,
  useApi,
  Button,
  Link,
  Modal,
  TextBlock,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  const {ui} = useApi();

  return (
    <Link
      overlay={
        <Modal
          id="my-modal"
          padding
          title="Return policy"
        >
          <TextBlock>
            We have a 30-day return policy.
          </TextBlock>
          <Button
            onPress={() =>
              ui.overlay.close('my-modal')
            }
          >
            Close
          </Button>
        </Modal>
      }
    >
      Return policy
    </Link>
  );
}

React

import {
  reactExtension,
  useApi,
  Button,
  Link,
  Modal,
  TextBlock,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  const {ui} = useApi();

  return (
    <Link
      overlay={
        <Modal
          id="my-modal"
          padding
          title="Return policy"
        >
          <TextBlock>
            We have a 30-day return policy.
          </TextBlock>
          <Button
            onPress={() =>
              ui.overlay.close('my-modal')
            }
          >
            Close
          </Button>
        </Modal>
      }
    >
      Return policy
    </Link>
  );
}

JavaScript

import {
  extension,
  Button,
  Link,
  Modal,
  TextBlock,
} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.block.render',
  (root, {ui}) => {
    const modalFragment = root.createFragment();
    const modal = root.createComponent(
      Modal,
      {
        id: 'my-modal',
        padding: true,
        title: 'Return policy',
      },
      root.createComponent(
        TextBlock,
        {},
        'We have a 30-day return policy.',
      ),
      root.createComponent(
        Button,
        {
          onPress: () =>
            ui.overlay.close('my-modal'),
        },
        'Close',
      ),
    );
    modalFragment.appendChild(modal);

    const link = root.createComponent(
      Link,
      {
        overlay: modalFragment,
      },
      'Return policy',
    );

    root.appendChild(link);
  },
);

Anchor to RelatedRelated

ReferenceTargets

ReferenceComponents

ReferenceConfiguration

LearnTutorials

Was this page helpful?