useEmbedNavigator

useEmbedNavigator is the low-level host ↔ iframe bridge used by Frame. Most apps should set onArtifactOpen on AiqlProvider instead of calling this hook directly. Use it when you build a custom iframe wrapper and need to:

Drive in-iframe navigation (NAVIGATE / PREFETCH)
Wait for EMBED_READY, then send a chat message (SEND_MESSAGE)
Handle ARTIFACT_OPEN from artifact cards inside the embed

For Chat, Brainstorm, and Analyze, prefer onReady and ref.sendMessage on Chat, Canvas, or Dashboard. Call sendMessage after onReady. The embed keeps the text until its chat can send, then starts the run.

Import

import { useEmbedNavigator, EMBED_MESSAGE } from "@aiql.io/react";

Message protocol

All messages use window.postMessage. The host validates event.origin and event.source against the iframe.

Host → iframe

`type`	Payload	Description
`NAVIGATE`	`{ path: string, replace: boolean }`	Push or replace a path inside the embed app router.
`PREFETCH`	`{ path: string }`	Prefetch a path inside the embed.
`SEND_MESSAGE`	`{ text: string }`	Send a user message into the Chat, Brainstorm, or Analyze chat and start the run.

Outbound messages are queued until the iframe announces ready.

Iframe → host

`type`	Payload	Description
`EMBED_READY`	—	Iframe NavBridge is listening. Flushes the outbound queue.
`ROUTE_CHANGED`	`{ path: string }`	Current embed pathname (and search) after a client navigation.
`ARTIFACT_OPEN`	`{ artifact: { type, id }, path: string }`	User clicked an artifact card. Prefer handling this via `onArtifactOpen`.

EMBED_MESSAGE exports the string constants for these types.

ARTIFACT_OPEN payload

{
  type: "ARTIFACT_OPEN",
  artifact: {
    type: "canvas" | "dashboard" | "presentation" | "inquiry" | "document" | "written-document",
    id: string,
  },
  path: string, // e.g. /observatory/{workspaceId}/brainstorm/{id}
}

Inside /embed/*, artifact open links call preventDefault and post this message instead of navigating. Outside embed mode they still open in a new tab.

Usage

import { useRef } from "react";
import { useEmbedNavigator, type ArtifactOpenEvent } from "@aiql.io/react";

function CustomFrame({
  src,
  origin,
  onArtifactOpen,
}: {
  src: string;
  origin: string;
  onArtifactOpen?: (event: ArtifactOpenEvent) => void;
}) {
  const iframeRef = useRef<HTMLIFrameElement>(null);
  const { isReady, navigate, prefetch, sendMessage } = useEmbedNavigator(
    iframeRef,
    origin,
    onArtifactOpen,
  );

  return (
    <>
      <button
        type="button"
        disabled={!isReady}
        onClick={() => navigate("/embed/ws/explore/abc", { replace: true })}
      >
        Open inquiry
      </button>
      <button
        type="button"
        disabled={!isReady}
        onClick={() => sendMessage("Summarize the latest quarter")}
      >
        Send message
      </button>
      <iframe ref={iframeRef} src={src} title="AiQL" />
    </>
  );
}

API Reference

Parameters

Argument	Type	Description
`iframeRef`	`RefObject<HTMLIFrameElement \| null>`	Ref to the embed iframe.
`origin`	`string \| null`	Expected iframe origin (from the embed URL). Messages from other origins are ignored.
`onArtifactOpen`	`(event: ArtifactOpenEvent) => void`	Optional. Called when a validated `ARTIFACT_OPEN` message arrives.

Return value

Field	Type	Description
`isReady`	`boolean`	`true` after `EMBED_READY`.
`navigate`	`(path: string, options?: { replace?: boolean }) => void`	Send `NAVIGATE` (queued until ready).
`prefetch`	`(path: string) => void`	Send `PREFETCH`.
`sendMessage`	`(text: string) => void`	Send `SEND_MESSAGE` (queued until ready). Empty text is ignored.
`reset`	`() => void`	Clear ready state and the outbound queue (for example before changing `iframe.src`).

ArtifactOpenEvent

Field	Type	Description
`type`	`AiqlArtifactType`	Artifact kind.
`id`	`string`	Artifact id.
`path`	`string`	Path from the iframe message.

See AiqlProvider for the recommended host integration.

React Components

React Hooks

React Server

Import

Message protocol

Host → iframe

Iframe → host

ARTIFACT_OPEN payload

Usage

API Reference

Parameters

Return value

ArtifactOpenEvent

​Import

​Message protocol

​Host → iframe

​Iframe → host

​ARTIFACT_OPEN payload

​Usage

​API Reference

​Parameters

​Return value

​ArtifactOpenEvent

Import

Message protocol

Host → iframe

Iframe → host

ARTIFACT_OPEN payload

Usage

API Reference

Parameters

Return value

ArtifactOpenEvent