Skip to main content

Iframe Integration

Qumra apps run inside an iframe in the Qumra admin panel. The platform communicates with your app using postMessage.

The useIframeNavigation hook listens for navigation messages from the parent Qumra admin window and routes your app accordingly.

app/utils/useIframeNavigation.tsx
import { useEffect } from "react";
import { useNavigate } from "react-router";

export function useIframeNavigation() {
  const navigate = useNavigate();

  useEffect(() => {
    const onMessage = (e: MessageEvent) => {
      if (!e.data || e.data.type !== "QUMRA_NAVIGATE") return;

      const path = String(e.data.path || "");
      if (!path.startsWith("/")) return;

      navigate(path);
    };

    window.addEventListener("message", onMessage);
    return () => window.removeEventListener("message", onMessage);
  }, [navigate]);
}

Integration in Root Layout​

Add the hook to your root layout so it is active on every page of your app.

app/root.tsx
import { useIframeNavigation } from "./utils/useIframeNavigation";

export function Layout({ children }: { children: React.ReactNode }) {
  useIframeNavigation();

  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Meta />
        <Links />
      </head>
      <body>
        {children}
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  );
}

Message Format​

The Qumra admin panel sends navigation messages using the postMessage API. The message object follows this structure:

{
  "type": "QUMRA_NAVIGATE",
  "path": "/about"
}
FieldTypeDescription
typestringAlways "QUMRA_NAVIGATE" for navigation events
pathstringThe target path to navigate to (must start with /)

Pages Configuration​

Define the pages your app exposes in the qumra.app.json manifest. Each page entry becomes a tab in the Qumra admin panel, allowing store owners to navigate between different sections of your app.

qumra.app.json
{
  "pages": [
    {
      "label": "Dashboard",
      "path": "/"
    },
    {
      "label": "Settings",
      "path": "/settings"
    },
    {
      "label": "Reports",
      "path": "/reports"
    }
  ]
}

When a store owner clicks on a tab, the admin panel sends a QUMRA_NAVIGATE message with the corresponding path to your iframe.

tip

Always include the useIframeNavigation hook in your root layout to enable seamless navigation from the Qumra admin panel.