Embed React components

@aiql.io/react embeds AiQL Observatory tools in your product via iframe. Your API key stays on the server. The browser only receives a short-lived workspace-scoped embed token.

Prerequisites

React 18+
An AiQL API key and workspace ID (set as AIQL_API_KEY and AIQL_WORKSPACE_ID on your server)
A Next.js App Router app, or any backend that can expose a token endpoint

Try it live

Use the playground below like the API reference: leave fields empty for the shared demo, or enter your own API key and IDs, then click Preview.

Install

npm install @aiql.io/react

pnpm add @aiql.io/react

yarn add @aiql.io/react

Mint an embed token

Create a server route that mints a workspace-scoped token. The browser never sees your API key. Next.js App Router — app/api/aiql/route.ts:

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

export const GET = createNextHandler();

Express:

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

app.get("/api/aiql", createExpressHandler());

See Server handlers for options and other frameworks.

Fetch the token and render

useToken() fetches from /api/aiql and refreshes before expiry. Wrap your components in AiqlProvider, then render one or more embeds.

import {
  AiqlProvider,
  Canvas,
  Chat,
  Dashboard,
  KnowledgeGraph,
  Preview,
  Presentation,
  useToken,
} from "@aiql.io/react";

function App() {
  const { token, status, error, reload } = useToken();

  if (status === "loading" || status === "idle") {
    return <p>Loading…</p>;
  }

  if (status === "error" || !token) {
    return (
      <div>
        <p>{error ?? "Failed to load token"}</p>
        <button type="button" onClick={reload}>
          Retry
        </button>
      </div>
    );
  }

  return (
    <AiqlProvider token={token} theme="auto">
      <Canvas canvasId="your-canvas-id" title="My canvas" />
      <Dashboard dashboardId="your-dashboard-id" title="My dashboard" />
      <Chat chatId="your-chat-id" title="Ask the graph" />
      <KnowledgeGraph documentId="your-document-id" title="Knowledge graph" />
      <Preview documentId="your-document-id" title="Source preview" />
      <Presentation presentationId="your-presentation-id" title="Presentation" />
    </AiqlProvider>
  );
}

You can mint the token some other way and pass it to AiqlProvider without using useToken.

Send a message

Chat, Canvas, and Dashboard accept a message from your app. Wait for onReady, then call sendMessage on the ref. The embed queues the text until its chat can send, then starts the run.

import { useRef } from "react";
import { Chat, type EmbedChatHandle } from "@aiql.io/react";

const ref = useRef<EmbedChatHandle>(null);

<Chat
  ref={ref}
  inquiryId={inquiryId}
  onReady={() => ref.current?.sendMessage("Summarize the latest quarter")}
/>

Canvas and Dashboard use the same handle. A send while a response is already streaming is ignored. Details are on Chat, Canvas, and Dashboard.

Choose a component

Component	What it embeds	Docs
`AiqlProvider`	Token + theme context for the subtree	Provider
`Canvas`	A saved canvas by ID	Canvas
`Dashboard`	A saved dashboard by ID	Dashboard
`Chat`	A chat / inquiry by ID	Chat
`KnowledgeGraph`	A document knowledge graph by ID	Knowledge Graph
`Preview`	A source document preview by ID	Source Preview
`Presentation`	A presentation/deck by ID (edit, themes/fonts, Present mode)	Presentation
`Frame`	Low-level iframe builder for custom tools	Frame

Environment variables

Variable	Where	Description
`AIQL_API_KEY`	Server	API key used to mint embed tokens
`AIQL_WORKSPACE_ID`	Server	Workspace the token is scoped to

Generate an API key in the Dashboard.

Embed tokens are workspace-scoped. /embed/* routes allow framing from any origin (frame-ancestors *). Access is still gated by the embed JWT. Never expose AIQL_API_KEY to the browser.

Next step

Explore the full React SDK reference: overview, hooks, and server.

Tools

Pipeline

Workspace

Embedding

Embed React components

Prerequisites

Try it live

Install

Mint an embed token

Fetch the token and render

Send a message

Choose a component

Environment variables

Next step

​Prerequisites

​Try it live

​Install

​Mint an embed token

​Fetch the token and render

​Send a message

​Choose a component

​Environment variables

​Next step

Prerequisites

Try it live

Install

Mint an embed token

Fetch the token and render

Send a message

Choose a component

Environment variables

Next step