Frame

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

import { Frame } from "@aiql.io/react";

Usage

Basic

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

<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

<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. Prefer Canvas, Dashboard, Chat, KnowledgeGraph, Preview, or Presentation when you know the tool in advance. For artifact open events and the postMessage protocol, see AiqlProvider and useEmbedNavigator.

React Components

React Hooks

React Server

Import

Usage

Basic

Tools

Custom loading and error UI

API Reference

Frame props

​Import

​Usage

​Basic

​Tools

​Custom loading and error UI

​API Reference

​Frame props

Import

Usage

Basic

Tools

Custom loading and error UI

API Reference

Frame props