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 UI API lets you display brief, non-disruptive notification messages to customers using toast notifications. Use this API to confirm successful actions, report errors, or surface contextual feedback without interrupting the customer workflow.

Note

In API version 2025-10 and later, this functionality moved to the Toast API.

Anchor to Use casesUse cases

Confirm a completed action: Show a success toast after the customer saves a preference, submits a form, or completes an operation.
Surface an error message: Display an error toast when a backend request fails or an action can't be completed, so the customer knows something went wrong.
Provide status updates: Notify the customer that a background process like data syncing or a submission has completed.

Support

Targets (25)

Supported targets

Anchor to PropertiesProperties

The UI API object provides toast notification functionality for customer account extensions. Access the following properties on the API object to show brief, non-blocking notification messages to the customer.

Anchor to ui ui required: Triggers platform-level UI interactions, such as displaying toast notifications. Use this to show success or error messages in response to customer actions.

Ui

Triggers platform-level UI interactions from your extension, such as displaying toast notifications. Use the UI API to show success or error messages in response to customer actions.

forceDataRefresh
Refresh data so the surrounding information on the page is updated. The `content` string will appear in a toast message after refresh, to confirm the action was successful. To request access to this API: 1. Go to your partner dashboard and click **Apps**. 2. Select the app you need to request access for. 3. Click **API access**. 4. Under **Access force data refresh**, click **Request access**.
```
(content: string) => Promise<void>
```
overlay
An overlay is a contextual element on top of the main interface that provides additional information or functionality.
```
{ close(overlayId: string): void; }
```
toast
The Toast API displays a non-disruptive message that displays at the bottom of the interface to provide quick, at-a-glance feedback on the outcome of an action. How to use: - Use toasts to confirm successful actions. - Aim for two words. - Use noun + past tense verb format. For example, \`Changes saved\`. For errors, or information that needs to persist on the page, use a [banner](/docs/api/customer-account-ui-extensions/2025-07/components/feedback/banner) component.
```
{ show(content: string): void; }
```

Examples

React

import React, {useState} from 'react';

import {

reactExtension,

useApi,

Button,

Select,

Modal,

} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension('customer-account.page.render', () => (

));

function Extension() {

const [selectedAddress, setSelectedAddress] = useState();

const [pickupAddress, setPickupAddress] = useState();

const {i18n, ui} = useApi<'customer-account.page.render'>();

return (

<Modal>

<Select

onChange={(value) => {

setSelectedAddress(value);

}}

label="Pickup Address Options"

value="1"

options={[

{

value: '1',

label: 'Address 1',

{

value: '2',

label: 'Address 2',

{

value: '3',

label: 'Address 3',

{

value: '4',

label: 'Address 4',

]}

<Button

onPress={() => {

setPickupAddress(selectedAddress);

ui.toast.show('Selection saved');

}}

Save

</Button>

</Modal>

);

}

Examples

Description

Display a toast notification after the customer saves a pickup address selection. This example uses `ui.toast.show()` from `useApi()` to confirm the action.

React

import React, {useState} from 'react';
import {
  reactExtension,
  useApi,
  Button,
  Select,
  Modal,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension('customer-account.page.render', () => (
  <Extension />
));
function Extension() {
  const [selectedAddress, setSelectedAddress] = useState();
  const [pickupAddress, setPickupAddress] = useState();
  const {i18n, ui} = useApi<'customer-account.page.render'>();
  return (
    <Modal>
      <Select
        onChange={(value) => {
          setSelectedAddress(value);
        }}
        label="Pickup Address Options"
        value="1"
        options={[
          {
            value: '1',
            label: 'Address 1',
          },
          {
            value: '2',
            label: 'Address 2',
          },
          {
            value: '3',
            label: 'Address 3',
          },
          {
            value: '4',
            label: 'Address 4',
          },
        ]}
      />
      <Button
        onPress={() => {
          setPickupAddress(selectedAddress);
          ui.toast.show('Selection saved');
        }}
      >
        Save
      </Button>
    </Modal>
  );
}

Anchor to Best practicesBest practices

Keep messages short: Toast messages should be a few words that confirm what happened, like "Selection saved" or "Submitted successfully". Avoid long sentences.
Don't rely on toasts for critical information: Toasts disappear automatically. If the customer needs to take action, use a banner or inline message instead.

Anchor to LimitationsLimitations

Toast messages dismiss automatically after a short duration. You can't control how long they remain visible.
Only one toast can be displayed at a time. If you trigger multiple toasts in quick succession, earlier ones may be replaced.
Toast notifications don't support interactive elements like links or buttons. Use them for passive feedback only.

Was this page helpful?