Loading...
; // Only show login for managed auth — other modes handle auth externally if (!isAuthenticated && authMode === "managed") { returnLoading...
; return (-
{conversations.map((c) => (
- setSelectedId(c.id)}> {c.title ?? "Untitled"} {/* Toggle star — second arg is the desired starred state */} ))}
| {col} | ))}
|---|
| {String(row[col] ?? "")} | ))}
{result.explanation}
)}Exploring schema...
;
}
return (
{/* args.command contains the explore command that was run */} Explore: {String(args.command ?? "semantic layer")}
{result}
Running Python...
;
}
if (!result.success) {
return (
Execution failed
{result.error}
{result.output && {result.output}}
{/* Text output */}
{result.output && (
))}
{/* Interactive Recharts data — render with your preferred chart library */}
{result.rechartsCharts?.map((chart, i) => (
))}
{/* Tabular output */}
{result.table && (
)}
);
}
```
Custom / Plugin Tools [#custom--plugin-tools]
Any tool name can have a custom renderer. Plugin tools (e.g. from BigQuery, Salesforce, or custom plugins) are passed through with `ToolRendererProps{result.output}
)}
{/* Static chart images */}
{result.charts?.map((chart, i) => (
{chart.type} chart — {chart.categoryKey} vs {chart.valueKeys.join(", ")}
{/* Plug in your own chart component here */}{JSON.stringify(chart.data.slice(0, 3), null, 2)}
| {col} | ))}
|---|
| {String(cell ?? "")} | ))}
Searching docs...
;
// Cast to your expected shape
const data = result as { results: { title: string; url: string }[] };
return (
-
{data.results.map((doc, i) => (
- {doc.title} ))}
{messages.map((msg) =>
msg.parts?.map((part, i) => {
if (part.type === "text") return
);
}
```
***
CSS Customization Guide [#css-customization-guide]
The Atlas widget uses CSS custom properties (variables) scoped to `.atlas-root` for all visual design tokens. These follow the [shadcn/ui](https://ui.shadcn.com/) neutral base with the [OKLCH color space](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/oklch).
Quick Reference [#quick-reference]
All variables are listed in the [CSS Variables](#css-variables) section above. Here are the most common customization recipes.
Brand Color Override [#brand-color-override]
Change the primary brand color across the widget — affects buttons, links, and focus rings:
{part.text}
; if (part.type === "tool-invocation") { // Access tool name, args, and result from the part const { toolName, args, result, state } = part.toolInvocation; const isLoading = state !== "result"; if (toolName === "executeSQL" && result) { const sqlResult = result as SQLToolResult; // Render your custom SQL table here } } return null; }), )}Atlas
{{ part.text }}
{{ part.text }}
{{ toolName === "executeSQL" ? "Executing query..." : "Running command..." }}
SQL
{{ input.explanation ?? "Query result" }}
{{ rows.length }} row{{ rows.length !== 1 ? "s" : "" }}
| {{ col }} |
|---|
| {{ row[col] == null ? "\u2014" : row[col] }} |
$ {{ input.command }}
{{ output }}
Tool: {{ toolName }}
```
The key data shapes:
* **`executeSQL` output** -- `{ success, columns, rows, truncated }` on success, or `{ success: false, error }` on failure. Use `rows.length` to get the row count.
* **`explore` output** -- a plain string (stdout of the command).
* **`state`** -- check for `"output-available"` to know when the result is ready. Other states: `"input-streaming"`, `"input-available"`, `"output-error"`, `"output-denied"`.
* **Tool detection** -- use `isToolUIPart(part)` from `"ai"` (not `part.type === "tool-invocation"`).
See the [Data Stream Protocol](/frameworks/overview#tool-call-parts-ai-sdk-v6) section for the full part structure and a concrete example.
6\. Synchronous queries (alternative) [#6-synchronous-queries-alternative]
If you don't need streaming, use the JSON query endpoint instead:
```typescript
// composables/useAtlasQuery.ts
export async function queryAtlas(question: string) {
const config = useRuntimeConfig();
const apiUrl = config.public.atlasApiUrl || "";
const res = await $fetch(`${apiUrl}/api/v1/query`, {
method: "POST",
body: { question },
headers: {
"Content-Type": "application/json",
},
});
return res;
}
```
See [Bring Your Own Frontend](/frameworks/overview) for the full architecture and what `@atlas/web` adds on top.
---
# SvelteKit (/frameworks/sveltekit)
Integrate Atlas into a SvelteKit app using `@ai-sdk/svelte`.
> **Prerequisites:** A running Atlas API server. See [Bring Your Own Frontend](/frameworks/overview) for architecture and common setup.
Atlas
{#each $messages as m (m.id)}
{#if m.role === "user"}
{:else}
{#each m.parts ?? [] as part, i}
{#if part.type === "text"}
{part.text}
{/if} {/each}
{#each m.parts ?? [] as part, i}
{#if part.type === "text" && part.text.trim()}
{/if}
{/each}
{part.text}
{:else if isToolUIPart(part)}
{toolName === "executeSQL" ? "Executing query..." : "Running command..."}
{:else if toolName === "executeSQL" && sqlResult}
SQL
{input.explanation ?? "Query result"}
{rows.length} row{rows.length !== 1 ? "s" : ""}
{#if columns.length && rows.length}
| {col} | {/each}
|---|
| {row[col] == null ? "\u2014" : row[col]} | {/each}
$ {input.command}
{output}
Tool: {toolName}
{/if}
```
The key data shapes:
* **`executeSQL` output** -- `{ success, columns, rows, truncated }` on success, or `{ success: false, error }` on failure. Use `rows.length` to get the row count.
* **`explore` output** -- a plain string (stdout of the command).
* **`state`** -- check for `"output-available"` to know when the result is ready. Other states: `"input-streaming"`, `"input-available"`, `"output-error"`, `"output-denied"`.
* **Tool detection** -- use `isToolUIPart(part)` from `"ai"` (not `part.type === "tool-invocation"`).
See the [Data Stream Protocol](/frameworks/overview#tool-call-parts-ai-sdk-v6) section for the full part structure and a concrete example.
6\. Conversation management [#6-conversation-management]
Atlas persists conversations server-side (requires `DATABASE_URL`). Here is a minimal Svelte module for listing, loading, and deleting conversations:
```typescript
// src/lib/atlas-conversations.ts
import { writable } from "svelte/store";
import { env } from "$env/dynamic/public";
const apiUrl = env.PUBLIC_ATLAS_API_URL ?? "";
export interface Conversation {
id: string;
userId: string | null;
title: string | null;
surface: string;
connectionId: string | null;
starred: boolean;
createdAt: string;
updatedAt: string;
}
export interface Message {
id: string;
conversationId: string;
role: "user" | "assistant" | "system" | "tool";
content: unknown;
createdAt: string;
}
export function createConversationStore(apiKey: () => string) {
const conversations = writable