UI Actions

UI actions let your plugin interact with the Whatalo admin shell — displaying feedback to the merchant without requiring your plugin to manage its own notification system.

All actions return Promise<ActionAck> and are subject to rate limits.

Toast Notifications

import { useAppBridge } from "@whatalo/plugin-sdk/bridge";

function SaveButton() {
  const bridge = useAppBridge();

  async function handleSave() {
    await saveData();

    bridge.toast.show("Changes saved!", {
      description: "Your settings have been updated.",
      variant: "success", // "success" | "error" | "warning" | "info"
    });
  }

  return <button onClick={handleSave}>Save</button>;
}

The description is optional. When omitted, only the main message is shown.

Modals

Open a URL from your plugin inside a modal overlay in the admin. Useful for confirmations, detail views, and secondary flows that shouldn't replace the main iframe.

const bridge = useAppBridge();

// Open a modal
await bridge.modal.open({
  title: "Order Details",
  url: "https://your-plugin.example.com/modal/order/123",
  width: 600,
  height: 400,
});

// Close the current modal from inside the modal iframe
await bridge.modal.close();

Modal Security Rules

• Only URLs from your plugin's registered origin are allowed. The platform validates against the appUrl domain.
• The following URL protocols are blocked: javascript:, data:, blob:, file:, vbscript:
• Localhost URLs are permitted in development mode only.
• Modal iframes use a stricter sandbox policy than the main plugin iframe — allow-same-origin is not included, so the modal cannot access the parent page's cookies or storage.

Resize

Control the height of your plugin's iframe. The admin does not auto-resize the iframe — your plugin is responsible for reporting its content height.

const bridge = useAppBridge();

// Set a specific height in pixels
await bridge.resize(800);

Height constraints: minimum 200px, maximum 15000px, default 400px. Values outside this range are clamped silently.

Auto-Resize with useAutoResize

The plugin template includes a useAutoResize hook that observes your content's rendered height and calls bridge.resize() automatically:

import { useAutoResize } from "./components/whatalo-ui";

function App() {
  // Automatically reports content height on every render change
  useAutoResize();

  return <div>Your plugin content</div>;
}

This is the recommended approach for plugins with variable-height content.

ActionAck Type

Every action method returns a promise that resolves to this type:

interface ActionAck {
  type: "whatalo:ack";
  actionId: string;
  success: boolean;
  error?: string; // Present only when success is false
}

Common error values: "timeout" (no ack in 5s), "rate_limited", "invalid_url" (modal), "invalid_path" (navigate), "out_of_bounds" (resize).