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

# useAiql

> Read the embed token, theme, and artifact-open handler from AiqlProvider context.

`useAiql` returns the current `token`, `theme`, and optional `onArtifactOpen` handler from the nearest `AiqlProvider`. It throws if you call it outside a provider.

Prefer this hook for custom components that need the shared token. `Canvas`, `Dashboard`, `Chat`, and `Frame` already call it internally.

## Import

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

## Usage

### Basic

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

function TokenDebug() {
  const { token, theme } = useAiql();
  return (
    <pre>
      theme={theme}
      {"\n"}
      token={token.slice(0, 16)}…
    </pre>
  );
}
```

### Must be under AiqlProvider

```tsx theme={null}
<AiqlProvider token={token} theme="light">
  <TokenDebug />
</AiqlProvider>
```

Calling `useAiql()` outside `AiqlProvider` throws:

```
useAiql must be used within an AiqlProvider. Wrap your tree with <AiqlProvider token={token}>.
```

## API Reference

### Return value

| Field            | Type                                              | Description                                       |
| ---------------- | ------------------------------------------------- | ------------------------------------------------- |
| `token`          | `string`                                          | Embed JWT (or full embed URL) from the provider.  |
| `theme`          | `"light" \| "dark" \| "auto"`                     | Theme from the provider.                          |
| `onArtifactOpen` | `(event: ArtifactOpenEvent) => void \| undefined` | Optional host handler for `ARTIFACT_OPEN` events. |

See [`AiqlProvider`](/sdks/react/components/provider), [`useToken`](/sdks/react/hooks/use-token), and [`useEmbedNavigator`](/sdks/react/hooks/use-embed-navigator).