> ## 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.

# Frame

> Base iframe renderer for an arbitrary AiQL embed tool and resource.

`Frame` is the base embed component. `Canvas`, `Dashboard`, `Chat`, `KnowledgeGraph`, `Preview`, and `Presentation` wrap it with a fixed tool. Use `Frame` when you need to pass `tool` and `resourceId` yourself. It still reads `token` and `theme` from `AiqlProvider`.

Internally, `Frame` uses `useEmbedFrame` to build `https://app.aiql.io/embed/{workspaceId}/{tool}/{resourceId}?token=...&theme=...` from the JWT claims.

The package does not ship chrome or theme styles. There is no wrapper element — `Frame` renders the iframe directly (plus optional loading/error nodes). The only inline styles are an iframe reset (`border: 0`, `display: block`, `width/height: 100%`). Pass `className` / `style` onto the iframe, or size it from your parent layout.

The iframe `allow` attribute includes `clipboard-write` and `fullscreen`. Fullscreen lets presentation **Present** mode take over the screen when the host page allows it.

## Import

```tsx theme={null}
import { Frame } from "@aiql.io/react";
```

## Usage

### Basic

```tsx theme={null}
import { AiqlProvider, Frame, useToken } from "@aiql.io/react";

function Embed({ resourceId }: { resourceId: string }) {
  const { token, status } = useToken();
  if (status !== "ready" || !token) return null;

  return (
    <AiqlProvider token={token} theme="auto">
      <Frame tool="brainstorm" resourceId={resourceId} title="Canvas" />
    </AiqlProvider>
  );
}
```

### Tools

```tsx theme={null}
<Frame tool="brainstorm" resourceId={canvasId} />
<Frame tool="analyze" resourceId={dashboardId} />
<Frame tool="explore" resourceId={inquiryId} />
<Frame tool="knowledge" resourceId={documentId} />
<Frame tool="preview" resourceId={documentId} />
<Frame tool="present" resourceId={presentationId} />
```

### Custom loading and error UI

```tsx theme={null}
<Frame
  tool="analyze"
  resourceId={dashboardId}
  renderLoading={() => <Spinner />}
  renderError={(message) => <ErrorBanner message={message} />}
/>
```

## API Reference

### Frame props

| Prop             | Type                                                                              | Default     | Description                                                                                                 |
| ---------------- | --------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------- |
| `tool`           | `"brainstorm" \| "analyze" \| "explore" \| "knowledge" \| "preview" \| "present"` | —           | Required. Embed tool.                                                                                       |
| `resourceId`     | `string`                                                                          | —           | Required. Canvas, dashboard, inquiry, document, or presentation id.                                         |
| `params`         | `Record<string, string \| number \| undefined>`                                   | —           | Optional query params appended to the embed URL (e.g. `page`, `chunkId` for preview).                       |
| `title`          | `string`                                                                          | —           | iframe `title` attribute.                                                                                   |
| `className`      | `string`                                                                          | —           | Class name on the iframe.                                                                                   |
| `style`          | `CSSProperties`                                                                   | —           | Inline styles on the iframe (merged after the reset).                                                       |
| `navigationMode` | `"push" \| "replace"`                                                             | `"replace"` | How host-driven path changes update the iframe router.                                                      |
| `onArtifactOpen` | `(event: ArtifactOpenEvent) => void`                                              | —           | Called when the user opens an artifact card in this iframe. Overrides the provider handler for this iframe. |
| `onLoad`         | `() => void`                                                                      | —           | Called when the iframe fires `load`.                                                                        |
| `onError`        | `(error: string) => void`                                                         | —           | Called when the embed URL cannot be built or the token is missing.                                          |
| `renderLoading`  | `() => ReactNode`                                                                 | —           | Custom loading UI. Renders nothing by default.                                                              |
| `renderError`    | `(error: string) => ReactNode`                                                    | —           | Custom error UI. Falls back to the error string.                                                            |

`token` and `theme` come from [`AiqlProvider`](/sdks/react/components/provider). Prefer [`Canvas`](/sdks/react/components/canvas), [`Dashboard`](/sdks/react/components/dashboard), [`Chat`](/sdks/react/components/chat), [`KnowledgeGraph`](/sdks/react/components/knowledge-graph), [`Preview`](/sdks/react/components/preview), or [`Presentation`](/sdks/react/components/presentation) when you know the tool in advance.

For artifact open events and the postMessage protocol, see [`AiqlProvider`](/sdks/react/components/provider#artifact-open-events) and [`useEmbedNavigator`](/sdks/react/hooks/use-embed-navigator).