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:

Overlay

Requires access to the Chat in checkout extensions scope. Request access in the Partner Dashboard.

The overlay target adds a floating chat widget to the checkout page. Buyers can start a conversation without leaving checkout. Use it to connect buyers with a live agent or chatbot.

Anchor to Use casesUse cases

Live chat: Connect buyers with a support agent or chatbot who can answer questions while they check out.
Cart-aware conversations: Pass cart details and buyer identity to your chat platform so agents can see what's in the order when a conversation starts. See the Chat component reference for an example using onReady and postMessage.
Proactive outreach: Open the chat automatically when the cart value is high, the buyer is checking out for the first time, or the cart contains items that commonly generate questions.

Anchor to Overlay targetOverlay target

Use this target to add a chat widget that floats over the checkout page. This target accepts only the Chat component. Learn more about building chat applications for checkout.

Anchor to Render a chat overlay ,[object Object]Render a chat overlay target

purchase.checkout.chat.render

Set extensions.targeting.preloads.chat in your shopify.extension.toml file to the URL of your chat page. The Chat component loads this URL in an iframe with access to the App Bridge script for checkout.

The overlay starts in a minimized state (max 224x72 pixels). After the buyer interacts with the widget and your app calls window.resizeTo(), the overlay expands to a maximized state (max 415x700 pixels on desktop, 100% width and 93% height of the viewport on mobile). The overlay persists across all checkout steps and isn't tied to a specific section.

Examples

import {

Chat,

reactExtension,

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

export default reactExtension(

'purchase.checkout.chat.render',

() => <Extension />,

);

function Extension() {

return <Chat inlineSize={100} blockSize={50} />;

}

Examples

Description

Render a floating chat widget on the checkout page. This example mounts a Chat component with a defined width and height.

React

import {
  Chat,
  reactExtension,
} from '@shopify/ui-extensions-react/checkout';

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

function Extension() {
  return <Chat inlineSize={100} blockSize={50} />;
}

TS

import {extension, Chat} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.chat.render',
  (root) => {
    const chat = root.createComponent(Chat, {
      inlineSize: 100,
      blockSize: 50,
    });

    root.appendChild(chat);
  },
);

Anchor to Best practicesBest practices

Test sizing across states: The overlay enforces different size limits for minimized and maximized states. The values you set for inlineSize and blockSize are clamped to these limits, so the rendered size might not match your input. Test both states at checkout to verify dimensions.
Design for the minimized state: Buyers see the minimized overlay first. Use it to show a clear call to action, like a chat icon or short label, that invites interaction. Reserve detailed content for the maximized state after the buyer focuses the widget.

Anchor to LimitationsLimitations

Anchored position: The overlay is anchored to the bottom-right corner. There's no API to change the position.
HTTPS required: The preloads.chat URL must use HTTPS. Relative URLs are resolved against your app URL.
Single extension: Only one extension can be active at the chat target at any time.
Public apps only: Chat extensions are available to public apps for real-time customer support. Custom apps can't use chat extensions.

Was this page helpful?