Triggering Native Shopify UI with App Bridge

Why Not Just Use alert() or a React Modal Library?

Your "first principles" approach to learning makes this a perfect place to start. Why do we need App Bridge for something as simple as a pop-up message? Why not use a standard library like react-modal or a simple alert()?

The answer lies in creating a seamless, native experience. Your app runs inside an <iframe> within the Shopify Admin.

• A standard alert() is jarring and doesn't match the Shopify look and feel.
• A modal from a generic React library would be trapped inside your app's <iframe>. It would be centered within your app's content area, not the entire Shopify Admin page, and the rest of the admin (like the main navigation) would remain active.

App Bridge solves this by acting as a "bridge" between your app and its host, the Shopify Admin. Your app sends a message (an "action") across this bridge, and the Shopify Admin itself renders the UI element.

To understand the benefits of this approach, please read the following section from the Shopify documentation.

This approach ensures that your app feels like an integrated part of Shopify, not a separate website embedded in a box.

Quick Feedback with Toast Messages

The simplest form of non-blocking feedback is a "toast" message. It's a small notification that appears briefly at the bottom of the screen to confirm an action or report a status.

Triggering a toast is a one-line command. Let's see it in action.

In our React-based app, the implementation looks like this. We get the app instance from the useAppBridge hook and call the toast.show() method.

import { Page, Button } from "@shopify/polaris";
import { useAppBridge } from "@shopify/app-bridge-react";

export default function ToastExample() {
  const app = useAppBridge();

  const showSuccessToast = () => {
    app.toast.show("Changes saved successfully!");
  };

  const showErrorToast = () => {
    app.toast.show("Failed to save changes", {
      isError: true,
      duration: 5000, // Show for 5 seconds
    });
  };

  return (
    <Page>
      <Button onClick={showSuccessToast}>Show Success Toast</Button>
      <Button onClick={showErrorToast}>Show Error Toast</Button>
    </Page>
  );
}

The toast.show() method is straightforward: the first argument is the message, and the second is an optional options object where you can control its duration and style (e.g., isError: true).

Focused Interaction with Modals

When you need to get the user's full attention—for a confirmation dialog, a form, or a resource selector—you'll use a modal. As we discussed, App Bridge modals feel native because the Shopify Admin renders them outside your app's <iframe>.

There are two primary ways to create and manage modals.

Method 1: Declarative Modal with Imperative Trigger

This is the most common pattern. You define the modal's structure in your JSX and then open it with a function call.

1. Define the Modal: Use the <Modal> and <TitleBar> components from @shopify/app-bridge-react. Give the modal a unique id.
2. Trigger the Modal: Use app.modal.show('your-modal-id') from an event handler, like a button's onClick.

The video you'll watch next demonstrates this pattern by creating a modal and then adding a title bar and buttons.

Let's look at a complete, practical example in React for a confirmation dialog. This is a pattern you will use constantly as a freelancer.

import { Page, Button } from "@shopify/polaris";
import { Modal, TitleBar, useAppBridge } from "@shopify/app-bridge-react";

export default function ConfirmationModalExample() {
  const app = useAppBridge();

  const handleDelete = () => {
    console.log("Deletion confirmed!");
    app.modal.hide("confirm-delete-modal");
    app.toast.show("Item deleted.");
  };

  return (
    <Page>
      {/* The button that opens the modal */}
      <Button destructive onClick={() => app.modal.show("confirm-delete-modal")}>
        Delete Item
      </Button>

      {/* The Modal definition */}
      <Modal id="confirm-delete-modal">
        <p>This action cannot be undone. Are you sure you want to proceed?</p>
        <TitleBar title="Confirm deletion">
          <button variant="primary" tone="critical" onClick={handleDelete}>
            Delete
          </button>
          <button onClick={() => app.modal.hide("confirm-delete-modal")}>
            Cancel
          </button>
        </TitleBar>
      </Modal>
    </Page>
  );
}

Notice how we use app.modal.hide('confirm-delete-modal') to close the modal programmatically.

Method 2: Controlled Modal with the open Prop

Alternatively, you can control the modal's visibility using React state, just like you would with any other React component. This is useful when the modal's visibility is tied to your application's state rather than a direct, one-off action.

For a detailed look at this and other modal configurations, the Shopify developer documentation is an excellent resource.

Here's how the state-controlled pattern looks:

import { Page, Button } from "@shopify/polaris";
import { Modal, TitleBar } from "@shopify/app-bridge-react";
import { useState } from "react";

export default function ControlledModalExample() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <Page>
      <Button onClick={() => setIsOpen(true)}>Open Modal</Button>

      <Modal open={isOpen} onHide={() => setIsOpen(false)}>
        <p>This modal is controlled by React state.</p>
        <TitleBar title="Controlled Modal">
          <button variant="primary" onClick={() => setIsOpen(false)}>
            Close
          </button>
        </TitleBar>
      </Modal>
    </Page>
  );
}

Conclusion

In this lesson, we learned how to create a polished and professional user experience by providing clear feedback through native Shopify UI elements. By using App Bridge actions, we ensure our app feels deeply integrated with the Shopify Admin.

Key Takeaways:

• App Bridge is essential for triggering native UI elements like toasts and modals to maintain a consistent UX.
• Toasts, triggered by app.toast.show(), are used for simple, non-blocking notifications.
• Modals are for focused, blocking interactions and can be created in two main ways:
  1. Defined with the <Modal id="..."> component and triggered imperatively with app.modal.show('...').
  2. Controlled declaratively using React state and the open prop on the <Modal> component.
• The choice between these modal patterns depends on the complexity of the modal's content and state.

In our next lesson, we will shift our focus from the admin to the storefront. You will learn about Theme App Extensions, a powerful mechanism that allows your app to inject functionality and UI elements directly into a merchant's online store theme. This is a critical skill for building many types of Shopify apps.