@useatlas/react

@useatlas/react

Embeddable Atlas chat UI for React applications.

Installation

bun add @useatlas/react

Usage

import { AtlasChat } from "@useatlas/react";
import "@useatlas/react/styles.css";

function App() {
  return <AtlasChat apiUrl="https://api.example.com" apiKey="your-key" />;
}

Custom Tool Renderers

Override how SQL results, charts, explore output, and Python results render inside the widget using the toolRenderers prop. This example assumes you have already imported the styles as shown above.

import { AtlasChat, type ToolRendererProps, type SQLToolResult } from "@useatlas/react";

function MySQLRenderer({ result, isLoading }: ToolRendererProps<SQLToolResult | null>) {
  if (isLoading || !result) return <div>Running query...</div>;
  if (!result.success) return <div>Query failed: {result.error}</div>;

  return (
    <div>
      <h3>Results ({result.rows.length} rows)</h3>
      <table>
        <thead>
          <tr>{result.columns.map((col) => <th key={col}>{col}</th>)}</tr>
        </thead>
        <tbody>
          {result.rows.map((row, i) => (
            <tr key={i}>
              {result.columns.map((col) => <td key={col}>{String(row[col] ?? "")}</td>)}
            </tr>
          ))}
        </tbody>
      </table>
    </div>
  );
}

function App() {
  return (
    <AtlasChat
      apiUrl="https://api.example.com"
      apiKey="your-key"
      toolRenderers={{
        executeSQL: MySQLRenderer,
      }}
    />
  );
}

Available tool names

Tool Name	Result Type	Description
executeSQL	SQLToolResult	SQL query results with columns and rows
explore	ExploreToolResult	Semantic layer exploration output (string)
executePython	PythonToolResult	Python execution results with optional charts and tables

Custom renderers for any tool name are supported — just add the tool name as a key in the toolRenderers map. Tools without a custom renderer use the built-in defaults.

Renderer props

Every renderer receives ToolRendererProps<T>:

Prop	Type	Description
toolName	string	Name of the tool being rendered
args	Record<string, unknown>	Input arguments passed to the tool
result	T	Tool output. Built-in tool types include | null for the loading state
isLoading	boolean	Whether the tool invocation is in progress

Error Handling

The widget handles errors at three levels — render errors (error boundary), API/network errors (error banner), and widget-level errors (postMessage). Each is automatic; you only need to listen if you want to react in your host application.

Error States

Error	What the user sees	Auto-recovery
API unreachable	"Unable to connect to Atlas." with a retry button	No — user must retry
Auth failure	Auth-mode-specific message (e.g. "Your session has expired.")	No — requires re-auth
Offline	"You appear to be offline."	Yes — auto-retries when navigator.onLine restores
Rate limited	"Too many requests." with countdown timer	Yes — auto-retries after countdown
Server error (5xx)	"Something went wrong on our end." with retry button	No — user must retry
Render crash	"Something went wrong." with a try-again button (error boundary)	No — user must click retry

Listening for Errors via postMessage

When embedded as an iframe, the widget emits atlas:error messages to the parent window on every error:

window.addEventListener("message", (event) => {
  if (event.origin !== "https://your-atlas-api.example.com") return;

  if (event.data?.type === "atlas:error") {
    const { code, message, detail, retryable } = event.data.error;
    // code: "api_unreachable" | "auth_failure" | "rate_limited_http" | "offline" | "server_error" | ChatErrorCode
    // retryable: true for transient errors, false for permanent ones
    console.error(`[Atlas] ${code}: ${message}`);
  }
});

Listening for Errors via the Programmatic API

When using the script tag loader, use Atlas.on("error", ...):

Atlas.on("error", (detail) => {
  // detail: { code?: string, message?: string }
  console.error("Widget error:", detail.code, detail.message);
});

Auth Token Refresh

When a managed auth session expires mid-conversation, the widget shows "Your session has expired. Please sign in again." For iframe embeds using external tokens (BYOT mode), refresh the token via postMessage:

// When your app refreshes a token, push it to the widget
function onTokenRefresh(newToken) {
  const iframe = document.querySelector("iframe");
  iframe.contentWindow.postMessage(
    { type: "auth", token: newToken },
    "https://your-atlas-api.example.com",
  );
}

For the script tag loader:

Atlas.setAuthToken(newToken);

CSP Configuration

If your site uses a Content Security Policy, add the Atlas API domain to these directives:

Content-Security-Policy:
  script-src 'self' https://your-atlas-api.example.com;
  frame-src 'self' https://your-atlas-api.example.com;
  connect-src 'self' https://your-atlas-api.example.com;

See the Embedding Widget guide for full CSP details.

Headless Hooks

For fully custom UIs, use the hooks entry point. Tool renderer types are also available here:

import { AtlasProvider, useAtlasChat } from "@useatlas/react/hooks";
import type { ToolRendererProps, SQLToolResult } from "@useatlas/react/hooks";

See the hooks documentation for details.