Skip to main content
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.

Chat

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

Use the Chat component to create real-time chat applications.

Note

The Chat component can only be added to the chat targets of checkout and Thank you pages.

Support
Targets (52)

Supported targets

Anchor to ChatPropsChatProps

Anchor to accessibilityLabel
accessibilityLabel
string

A label that describes the purpose or contents of the component. When set, it will be announced to users using assistive technologies and will provide them with more context.

Anchor to blockSize
blockSize
number

Adjust the block size.

Checkout imposes sizing restrictions for the component, therefore the size set may not be the actual size rendered.

number: size in pixels.

Learn more about block size on MDN.

Anchor to id
id
string

A unique identifier for the component. Use this to target the component in scripts or stylesheets, or to distinguish it from other instances of the same component.

Anchor to inlineSize
inlineSize
number

Adjust the inline size.

Checkout imposes sizing restrictions for the component, therefore the size set may not be the actual size rendered.

number: size in pixels.

Learn more about inline size on MDN.

Anchor to onMessage
onMessage
(event: ) => void

Callback when the embedded page sends a message.

Anchor to onReady
onReady
(event: ) => void

Callback when the embedded page is ready and a message port has been created to communicate with the host page.

Anchor to App Bridge for checkoutApp Bridge for checkout

The App Bridge script for checkout provides APIs that enables a secure communication channel between the Shopify checkout and the embedded application within the Chat iframe. It also offers convenient methods to perform common actions like resizing the iframe from within the application.

After App Bridge is set up in your app, you have access to the shopify global variable. This variable exposes the following App Bridge functionalities and configuration information:

The App Bridge script for checkout provides APIs that enable a secure communication channel between the Shopify checkout and the embedded application within the Chat iframe.

Anchor to config
config

The static configuration values that will not change during runtime.

Anchor to extension
extension

The references and APIs to the UI extension that helped bootstrap the iframe.

Anchor to idToken
idToken
() => Promise<string>

The ID token providing a set of claims as a signed JSON Web Token (JWT) with a TTL of 5 minutes. It can be used to ensure that requests came from a Shopify authenticated user. See the ID Token documentation and the session token API for more information.

Anchor to platform
platform
'browser' | 'shop-app' | 'pos'

The platform or application that the app is embedded within.

Anchor to surface
surface
'checkout'

The Shopify surface that the app is embedded within.

Anchor to visitor
visitor
() => Promise<>

Information about the current visitor.

Anchor to ExamplesExamples

Anchor to Basic ChatBasic Chat

Basic Chat

Example

Basic Chat

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

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

// This component requires the configuration of the `extensions.targeting.preloads.chat` in the extensions configuration file.
// Its value will be used as the `src` attribute of the Chat component.

function Extension() {
return <Chat inlineSize={100} blockSize={50} />;
}
import {extension, Chat} from '@shopify/ui-extensions/checkout';

// This component requires the configuration of the `extensions.targeting.preloads.chat` in the extensions configuration file.
// Its value will be used as the `src` attribute of the Chat component.

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

root.appendChild(chat);
});

Anchor to Resize the Chat iframe from the hosted applicationResize the Chat iframe from the hosted application

A very common action in your application will be to request a resize of the iframe. This is done through the App Bridge resizeTo() method. The following example resizes the iframe following the click of an activator button to show a dialog window.

Resize the Chat iframe from the hosted application

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

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

function Extension() {
return <Chat inlineSize={150} blockSize={50} />;
}
<!doctype html>
<html lang="en">
<head>
<script src="https://cdn.shopify.com/shopifycloud/checkout-web/assets/app-bridge-checkout.js"></script>
<style>
.dialog {
display: none;
}
.visible {
display: block;
}
</style>
</head>
<body>
<dialog class="dialog">
How can we help you today?
<button class="btn-close">Close</button>
</dialog>
<button class="btn-activator">Chat with us</button>

<script type="text/javascript">
const btnActivator = document.querySelector('.btn-activator');
const btnClose = document.querySelector('.btn-close');
const dialog = document.querySelector('.dialog');

// bind actions to the buttons
btnActivator.addEventListener('click', toggleDialog);
btnClose.addEventListener('click', toggleDialog);

function toggleDialog() {
// if the dialog is visible,
// - hide the dialog
// - resize the iframe to the button's size
if (dialog.classList.contains('visible')) {
dialog.classList.remove('visible');
shopify !== undefined && window.resizeTo(150, 50);

// if the dialog is not visible,
// - resize the iframe to the desired dialog's size
// - then show the dialog
} else {
shopify !== undefined && window.resizeTo(415, 700);
dialog.classList.add('visible');
}
}
</script>
</body>
</html>

Anchor to Communicate information between the hosted application and the UI extensionCommunicate information between the hosted application and the UI extension

Information can be passed between the hosted application and the UI extension through App Bridge. Extensions API are available in the UI extension and can be shared through that method.

Communicate information between the hosted application and the UI extension

import {
reactExtension,
useShippingAddress,
Chat,
} from '@shopify/ui-extensions-react/checkout';
import {retain} from '@remote-ui/rpc';
import type {ReadyEvent} from '@shopify/ui-extensions-react/checkout';

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

function Extension() {
/**
* Use the `useShippingAddress` hook to access the first name of the buyer.
*/
const {firstName} = useShippingAddress();

/**
* Define a variable to store the `postMessage` function
* so we can re-use outside of the onReady callback later if needed.
*/
let postMessage;

return (
<Chat
inlineSize={150}
blockSize={50}
onReady={({postMessage: postMessageParam}: ReadyEvent) => {
/**
* Save the `postMessage` function to the variable defined earlier.
*/
postMessage = postMessageParam;
retain(postMessage);

/**
* When the communication channel is ready, send a message to the hosted application
* using the `postMessage` provided as parameter.
*/
postMessage({
action: 'ping',
buyer: {
firstName,
},
});
}}
onMessage={(event: Event) => {
/**
* Listen for messages from the hosted application.
* If the action is `pong`, the communication channel is successful.
*/
if (event.data.action === 'pong') {
console.log('Messaging channel successful');
}
}}
/>
);
}
// Create a variable to store the buyer's first name.
// We'll be able to use this to personalize the chat experience.
let buyerFirstName;

// In the hosted application Javascript, listen for messages from the UI extension.
shopify.extension.port.onmessage = async (event) => {
// if the message's data has a ping action, respond with a pong
if (event.data.action === 'ping') {
buyerFirstName = event.data.buyer.firstName;

await shopify.extension.port.postMessage({
action: 'pong',
});
}
};

// Ensure the messagePort is ready to start sending and receiving messages.
shopify.extension.port.start();

Anchor to Chat source and query parametersChat source and query parameters

The src of the iframe rendered by Chat is provided by the preloads chat key in the extension configuration file. Shopify automatically appends query parameters to the URL which allows developers to verify the authenticity of the request and the identity of the merchant. We guarantee these tokens are valid and signed by Shopify.

Anchor to id_tokenid_token

The ID token providing a set of claims as a signed JSON Web Token (JWT) with a TTL of 5 minutes. It can be used to retrieve merchants information on the backend as well as ensure that requests came from a Shopify authenticated source. See the ID Token documentation for more information.

Anchor to localelocale

The locale of the shop that’s embedding the app, i.e. en-CA. This information is also available in the shopify global variable under config.

Anchor to handlehandle

The unique handle name of the UI extension as defined by the developer. This information is also available in the shopify global variable under extension.

Anchor to Chat dimensionsChat dimensions

To provide developers with the most flexibility when it comes to responsive changes, the iframe rendered in the page by Chat takes the full width and height of the browser window. Only a specific part of the iframe is visible, the rest is clipped.

The inlineSize and blockSize values set on the Chat component or changed through the App Bridge resizeTo() method dictates the bounding box of the visible part. That box is fixed and positioned in the bottom right corner of the iframe.

Your application can rely on the window’s dimension to change styles or apply specific behaviors to different window sizes. This allow developers to style their app as if as if the application would be outside an iframe. For example, CSS media queries can now work within the iframe.

Anchor to Getting started with App Bridge for checkoutGetting started with App Bridge for checkout

You must add App Bridge to your hosted chat application by including the script tag pointing to the app-bridge-checkout.js as the first script in the <head> section as seen in the example. The script loads directly from Shopify and keeps itself up-to-date.

Anchor to App Bridge’s global variableApp Bridge’s global variable

After App Bridge is set up in your app, you have access to the shopify global variable. This variable exposes various App Bridge functionalities, such as resizing the iframe or retrieving details of the shop.

The reference above list all the available methods and properties.

Alternatively, to explore all the functionality available on the shopify global variable:

  • Open the Chrome developer console while in checkout.
  • Switch the frame context to your app's iframe.
  • Enter shopify in the console.

Anchor to App Bridge’s CSS APIApp Bridge’s CSS API

Since the Chat iframe is clipped and fills the whole window as seen in the previous section, using percentage based sizes for its UI elements will most likely resolves in clipped content. As mentioned in the UX guidelines, Chat is constraint to specific maximum sizes on large and small screens set by Shopify. Setting a 100% width on an element will not be constraint to the visible size of the iframe, but to the whole window.

To remediate this issue, through App Bridge we offer a set of CSS custom properties with all the maximum dimensions defined in our UX guidelines. You can use these custom properties whether in Javascript or in the CSS of you application to set protections against overflowing content while using percentage based sizes. Using these properties will also reduce regressions if Shopify ever changes the maximum dimensions.

Was this page helpful?