@aiql.io/react embeds AiQL Observatory and Studio tools (Canvas, Dashboard, Chat, Knowledge Graph, Common Knowledge, Source Preview, and Presentation) in your product via iframe. Your API key stays on the server. The browser only receives a short-lived workspace-scoped embed token.
How it works
- Your backend mints a token with
@aiql.io/react/server(one-line Next.js or Express handler). useToken()fetches that token from/api/aiqland refreshes it before expiry.AiqlProvidershares the token (and theme) with the subtree.Canvas,Dashboard,Chat,KnowledgeGraph,CommonKnowledge,Preview, orPresentationbuilds the embed URL and renders the iframe.
Install
React 18+ is required as a peer dependency.Quick start
1. Create the token endpoint
SetAIQL_API_KEY and AIQL_WORKSPACE_ID on your server.
Next.js App Router — app/api/aiql/route.ts:
2. Fetch the token and render
AiqlProvider without using useToken.
Explore the API
Components
AiqlProvider, Canvas, Dashboard, Chat, KnowledgeGraph, CommonKnowledge, Preview, Presentation, and Frame.Hooks
useToken, useAiql, and useEmbedNavigator for tokens, context, and embed events.Server
One-line handlers that mint embed tokens on your backend.
Artifact open events
When chat (or another embed) shows an artifact card and the user clicks it, the iframe postsARTIFACT_OPEN to the host instead of navigating away. Handle it with onArtifactOpen on AiqlProvider so your app can route to its own pages (for example /brainstorm/{id}, /analyze/{id}, /present/{id}).
See useEmbedNavigator for the full postMessage protocol.
Environment variables
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.