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
Handle ARTIFACT_OPEN from artifact cards inside the embed

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.

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 } = useEmbedNavigator(
    iframeRef,
    origin,
    onArtifactOpen,
  );

  return (
    <>
      <button
        type="button"
        disabled={!isReady}
        onClick={() => navigate("/embed/ws/explore/abc", { replace: true })}
      >
        Open inquiry
      </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`.
`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