@tanstack/ai-svelte

Svelte 5 factory functions for TanStack AI, built on runes. To build your first chat, start with the Quick Start. For a typed chat layout, see Svelte Chat UI.

Installation#

npm i @tanstack/ai-svelte

pnpm add @tanstack/ai-svelte

yarn add @tanstack/ai-svelte

bun add @tanstack/ai-svelte

The factories are functions, not hooks, so their names start with create. Call them during component init.

createChat(options)#

Holds the messages and the run state of one chat, and talks to your server route.

<script lang="ts">
  import { createChat, fetchServerSentEvents } from "@tanstack/ai-svelte";

  let input = $state("");
  const chat = createChat({
    connection: fetchServerSentEvents("/api/chat"),
    threadId: "support-chat",
  });

  const handleSubmit = (e: Event) => {
    e.preventDefault();
    if (input.trim() && !chat.isLoading) {
      chat.sendMessage(input);
      input = "";
    }
  };
</script>

{#each chat.messages as message (message.id)}
  <div>
    <strong>{message.role}:</strong>
    {#each message.parts as part}
      {#if part.type === "text"}<span>{part.content}</span>{/if}
    {/each}
  </div>
{/each}
<form onsubmit={handleSubmit}>
  <input bind:value={input} />
  <button type="submit" disabled={chat.isLoading}>Send</button>
</form>

Options#

You must pass threadId. You must also pass connection or fetcher, not both.

The factory also takes the ChatClient callbacks (onResponse, onChunk, onFinish, onError, onInterruptStateChange, onCustomEvent) and the other client options. See ChatClient options.

To change forwardedProps or context after the chat starts, call chat.updateForwardedProps(value) or chat.updateContext(value).

Returns#

State fields are reactive getters backed by $state. Read them on the object, for example chat.messages. Do not destructure them, or you keep only the first value.

When the component is destroyed, the chat drops its connection and keeps its messages. When you are done with the chat, call dispose() yourself.

Example: tool approval#

A tool with needsApproval: true pauses the run. The pending call shows up in interrupts.

<script lang="ts">
  import { toolDefinition } from "@tanstack/ai";
  import { createChat, fetchServerSentEvents } from "@tanstack/ai-svelte";
  import { z } from "zod";

  const deleteFileTool = toolDefinition({
    name: "delete_file",
    description: "Delete a file",
    needsApproval: true,
    inputSchema: z.object({ path: z.string() }),
  });

  const chat = createChat({
    connection: fetchServerSentEvents("/api/chat"),
    threadId: "support-chat",
    tools: [deleteFileTool],
  });
</script>

{#each chat.interrupts as interrupt (interrupt.id)}
  {#if interrupt.kind === "tool-approval"}
    <div>
      <p>Approve: {interrupt.toolName}</p>
      <button onclick={() => interrupt.resolveInterrupt(true)}>Approve</button>
      <button onclick={() => interrupt.resolveInterrupt(false)}>Deny</button>
    </div>
  {/if}
{/each}

See Tool Approval for the server side.

createChatHook(options)#

Binds chat options once at module scope and returns a createChat factory that uses them.

import { createChatHook, fetchServerSentEvents } from "@tanstack/ai-svelte";

export const { createChat: createSupportChat } = createChatHook({
  connection: fetchServerSentEvents("/api/chat"),
});

// In a component: const chat = createSupportChat({ threadId: "support-1" })

The bound factory takes these per-call overrides: threadId, initialMessages, live, and forwardedProps. Keep tools, interrupts, and outputSchema on the factory options.

@tanstack/ai-svelte/ui has its own createChatHook that also returns typed UI components. See Svelte Chat UI.

Generation hooks#

Each factory runs one generation request and keeps its result. See Generation Hooks.

<script lang="ts">
  import { createGenerateImage, fetchServerSentEvents } from "@tanstack/ai-svelte";

  const image = createGenerateImage({
    connection: fetchServerSentEvents("/api/generate/image"),
    threadId: "image-studio",
  });
</script>

<button
  disabled={image.isLoading}
  onclick={() => image.generate({ prompt: "A mountain at sunset" })}
>
  Generate
</button>

Options: threadId (required), connection or fetcher, body, persistence, byok, byokProvider, devtools, onResult, onError, onProgress, onChunk.

Returns: generate(input), result, isLoading, error, status, stop(), reset(), runId, updateBody(body), and dispose(). The state fields are reactive getters. The factories do not clean up on their own. When you are done, call dispose().

createGenerateVideo also returns jobId and videoStatus, and takes onJobCreated and onStatusUpdate.

Realtime chat#

This package does not export a realtime factory. Use RealtimeClient, which this package re-exports. See Realtime Chat.

createAudioRecorder(options?)#

Records audio from the microphone. See Audio Recording.

Returns recording, isRecording, isSupported (reactive getters), start(), stop(), and cancel(). Pass onComplete to transform the recording. Then recording and stop() use the transformed type.

createByok(client)#

Subscribes to a BYOK keyring. The return value has a reactive snapshot getter. See Bring Your Own Key.

<script lang="ts">
  import { createByok } from "@tanstack/ai-svelte";
  import { byok } from "./byok";

  const byokState = createByok(byok);
  const openai = $derived(byokState.snapshot.status.openai);
</script>

<p>{openai && "masked" in openai ? openai.masked : "No key"}</p>

Keep the object and read byokState.snapshot in markup or $derived. If you destructure snapshot, you keep only the first value. The snapshot has status, locked, prompt, and storageError. Save a key from your own UI with byok.update(provider, value).

MCP App bridge#

This package does not export a bridge factory. Use createMcpAppBridge, which this package re-exports. See MCP Apps.

createRegisterWebMCPTools(tools, options?)#

Exposes client tools to the browser WebMCP API. Call it during component init. Svelte removes the tools when the component is destroyed. See WebMCP Tools.

<script lang="ts">
  import { createRegisterWebMCPTools } from "@tanstack/ai-svelte";
  import { searchProducts } from "./tools";

  createRegisterWebMCPTools([searchProducts], {
    onError: (error) => console.error(error),
  });
</script>

Options: toolOptions, context, and onError. context is required when a tool declares a required runtime context.

createPageWebMCPTools(options?)#

Reads the WebMCP tools that the page registered, as client tools. The tools field starts empty and updates when the page adds or removes a tool. Read it in a get tools() getter on createChat. See Page WebMCP Tools in Chat.

<script lang="ts">
  import { createPageWebMCPTools } from "@tanstack/ai-svelte";

  const page = createPageWebMCPTools({
    filter: (tool) => tool.origin === location.origin,
  });
</script>

<p>{page.tools.length} page tools</p>

Options: filter (return false to skip a tool) and onError.

Re-exports from @tanstack/ai-client#

You can import these from @tanstack/ai-svelte directly. See @tanstack/ai-client for details.

BYOK helpers (defineByok, defaultByokStorage, and more) are on the @tanstack/ai-svelte/byok subpath.

Types#

Pass a plain tools array to createChat or createChatClientOptions. Tool names, inputs, and outputs stay typed without as const. Import toolDefinition from @tanstack/ai.