> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiql.io/llms.txt
> Use this file to discover all available pages before exploring further.

# useEmbedNavigator

> postMessage bridge between the host page and an AiQL embed iframe.

`useEmbedNavigator` is the low-level host ↔ iframe bridge used by [`Frame`](/sdks/react/components/frame). Most apps should set [`onArtifactOpen` on `AiqlProvider`](/sdks/react/components/provider#artifact-open-events) 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

```tsx theme={null}
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

```ts theme={null}
{
  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

```tsx theme={null}
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`](/sdks/react/components/provider#artifact-open-events) for the recommended host integration.