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

# AiqlProvider

> Shares an embed token, theme, and optional artifact-open handler with Canvas, Dashboard, Chat, and Frame.

`AiqlProvider` is a pure context container. It does not fetch tokens. Pass a token from `useToken` or mint one yourself, then wrap the components that need it.

## Import

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

## Usage

### Basic

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

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

  if (status !== "ready" || !token) return null;

  return (
    <AiqlProvider token={token}>
      <Canvas canvasId="your-canvas-id" />
    </AiqlProvider>
  );
}
```

### Theme

```tsx theme={null}
<AiqlProvider token={token} theme="dark">
  <Canvas canvasId="your-canvas-id" />
</AiqlProvider>
```

`theme` defaults to `"auto"`, which follows the user's `prefers-color-scheme`.

### Multiple embeds

One provider can wrap several components that share the same workspace token:

```tsx theme={null}
<AiqlProvider token={token} theme="auto">
  <Canvas canvasId="canvas-1" />
  <Dashboard dashboardId="dashboard-1" />
</AiqlProvider>
```

### Artifact open events

When a user clicks an artifact card inside an embed (for example a canvas, dashboard, or presentation preview in [`Chat`](/sdks/react/components/chat)), the iframe posts an `ARTIFACT_OPEN` message to the parent. The SDK turns that into an `onArtifactOpen` callback so your host can navigate to its own routes instead of opening AiQL in a new tab.

Register the handler once on the provider so every embed under it receives it:

```tsx theme={null}
import { useRouter } from "next/navigation";
import { AiqlProvider, Chat, useToken } from "@aiql.io/react";
import type { ArtifactOpenEvent } from "@aiql.io/react";

function App() {
  const router = useRouter();
  const { token, status } = useToken();

  if (status !== "ready" || !token) return null;

  function handleArtifactOpen(event: ArtifactOpenEvent) {
    if (event.type === "canvas") {
      router.push(`/brainstorm/${event.id}`);
      return;
    }
    if (event.type === "dashboard") {
      router.push(`/analyze/${event.id}`);
      return;
    }
    if (event.type === "presentation") {
      router.push(`/present/${event.id}`);
    }
  }

  return (
    <AiqlProvider token={token} onArtifactOpen={handleArtifactOpen}>
      <Chat inquiryId={inquiryId} />
    </AiqlProvider>
  );
}
```

You can also pass `onArtifactOpen` on [`Chat`](/sdks/react/components/chat) or [`Frame`](/sdks/react/components/frame). A prop on the component overrides the provider handler for that iframe only.

See [`useEmbedNavigator`](/sdks/react/hooks/use-embed-navigator) for the postMessage shapes (`ARTIFACT_OPEN`, `EMBED_READY`, `NAVIGATE`, and related constants).

## API Reference

### AiqlProvider props

| Prop             | Type                                 | Default  | Description                                                                       |
| ---------------- | ------------------------------------ | -------- | --------------------------------------------------------------------------------- |
| `token`          | `string`                             | —        | Required. Embed JWT (or a full embed URL).                                        |
| `theme`          | `"light" \| "dark" \| "auto"`        | `"auto"` | Theme applied to embed iframes via the `theme` query param.                       |
| `onArtifactOpen` | `(event: ArtifactOpenEvent) => void` | —        | Called when the user opens an artifact card inside any embed under this provider. |
| `children`       | `ReactNode`                          | —        | Components that read the token from context.                                      |

### ArtifactOpenEvent

| Field  | Type               | Description                                                                                                     |
| ------ | ------------------ | --------------------------------------------------------------------------------------------------------------- |
| `type` | `AiqlArtifactType` | Artifact kind: `"canvas"`, `"dashboard"`, `"presentation"`, `"inquiry"`, `"document"`, or `"written-document"`. |
| `id`   | `string`           | Artifact id.                                                                                                    |
| `path` | `string`           | Observatory path from the iframe (for example `/observatory/{workspaceId}/brainstorm/{id}`).                    |