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

# React SDK

> Embed AiQL Canvas, Dashboard, Chat, Knowledge Graph, Common Knowledge, Source Preview, and Presentation in your React app with @aiql.io/react.

`@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

```mermaid theme={null}
sequenceDiagram
  participant Hook as useToken
  participant Back as Your /api/aiql
  participant App as app.aiql.io
  participant Prov as AiqlProvider
  participant Cmp as Canvas Dashboard Chat KnowledgeGraph CommonKnowledge Preview or Presentation
  Hook->>Back: GET /api/aiql
  Back->>App: Bearer AIQL_API_KEY
  App-->>Back: token, expiresAt
  Back-->>Hook: token, expiresAt
  Hook-->>Prov: token
  Prov-->>Cmp: token via context
  Cmp->>App: iframe /embed/.../?token=...
```

1. Your backend mints a token with `@aiql.io/react/server` (one-line Next.js or Express handler).
2. `useToken()` fetches that token from `/api/aiql` and refreshes it before expiry.
3. `AiqlProvider` shares the token (and theme) with the subtree.
4. `Canvas`, `Dashboard`, `Chat`, `KnowledgeGraph`, `CommonKnowledge`, `Preview`, or `Presentation` builds the embed URL and renders the iframe.

## Install

React 18+ is required as a peer dependency.

<CodeGroup>
  ```bash npm theme={null}
  npm install @aiql.io/react
  ```

  ```bash pnpm theme={null}
  pnpm add @aiql.io/react
  ```

  ```bash yarn theme={null}
  yarn add @aiql.io/react
  ```
</CodeGroup>

## Quick start

### 1. Create the token endpoint

Set `AIQL_API_KEY` and `AIQL_WORKSPACE_ID` on your server.

**Next.js App Router** — `app/api/aiql/route.ts`:

```ts theme={null}
import { createNextHandler } from "@aiql.io/react/server";

export const GET = createNextHandler();
```

**Express**:

```ts theme={null}
import { createExpressHandler } from "@aiql.io/react/server";

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

See [Server handlers](/sdks/react/server/handlers) for options and other frameworks.

### 2. Fetch the token and render

```tsx theme={null}
import { AiqlProvider, Canvas, 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" />
    </AiqlProvider>
  );
}
```

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

## Explore the API

<Columns cols={3}>
  <Card title="Components" href="/sdks/react/components/provider">
    `AiqlProvider`, `Canvas`, `Dashboard`, `Chat`, `KnowledgeGraph`, `CommonKnowledge`, `Preview`, `Presentation`, and `Frame`.
  </Card>

  <Card title="Hooks" href="/sdks/react/hooks/use-token">
    `useToken`, `useAiql`, and `useEmbedNavigator` for tokens, context, and embed events.
  </Card>

  <Card title="Server" href="/sdks/react/server/overview">
    One-line handlers that mint embed tokens on your backend.
  </Card>
</Columns>

## Artifact open events

When chat (or another embed) shows an artifact card and the user clicks it, the iframe posts `ARTIFACT_OPEN` to the host instead of navigating away. Handle it with `onArtifactOpen` on [`AiqlProvider`](/sdks/react/components/provider#artifact-open-events) so your app can route to its own pages (for example `/brainstorm/{id}`, `/analyze/{id}`, `/present/{id}`).

See [`useEmbedNavigator`](/sdks/react/hooks/use-embed-navigator) for the full postMessage protocol.

## 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](https://app.aiql.io).

<Note>
  Embed tokens are workspace-scoped. `/embed/*` routes allow framing from any origin (`frame-ancestors *`). Access is still gated by the embed JWT.
</Note>