@tanstack/ai-vue

Vue 3 composables for TanStack AI. To build your first chat, start with the Quick Start. For a typed chat layout, see Vue Chat UI.

Installation#

npm i @tanstack/ai-vue

pnpm add @tanstack/ai-vue

yarn add @tanstack/ai-vue

bun add @tanstack/ai-vue

useChat(options)#

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

<script setup lang="ts">
import { ref } from "vue";
import { useChat, fetchServerSentEvents } from "@tanstack/ai-vue";

const input = ref("");
const { messages, sendMessage, isLoading } = useChat({
  connection: fetchServerSentEvents("/api/chat"),
  threadId: "support-chat",
});

const handleSubmit = () => {
  if (input.value.trim() && !isLoading.value) {
    sendMessage(input.value);
    input.value = "";
  }
};
</script>

<template>
  <div>
    <div v-for="message in messages" :key="message.id">
      <strong>{{ message.role }}:</strong>
      <template v-for="(part, idx) in message.parts" :key="idx">
        <span v-if="part.type === 'text'">{{ part.content }}</span>
      </template>
    </div>
    <form @submit.prevent="handleSubmit">
      <input v-model="input" />
      <button type="submit" :disabled="isLoading">Send</button>
    </form>
  </div>
</template>

Options#

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

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

The composable watches forwardedProps, context, queue, and live. To change them after the chat starts, read reactive state in an option getter (for example get forwardedProps() { ... }). A change updates the current chat.

Returns#

State values are read-only Vue refs. Read .value in <script setup>. In <template>, Vue unwraps them, so use the bare name. Cleanup runs in onScopeDispose.

Example: tool approval#

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

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

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

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

<template>
  <template v-for="interrupt in interrupts" :key="interrupt.id">
    <div v-if="interrupt.kind === 'tool-approval'">
      <p>Approve: {{ interrupt.toolName }}</p>
      <button @click="interrupt.resolveInterrupt(true)">Approve</button>
      <button @click="interrupt.resolveInterrupt(false)">Deny</button>
    </div>
  </template>
</template>

See Tool Approval for the server side.

createChatHook(options)#

Binds chat options once at module scope and returns a useChat composable that uses them.

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

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

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

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

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

Generation hooks#

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

<script setup lang="ts">
import { useGenerateImage, fetchServerSentEvents } from "@tanstack/ai-vue";

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

<template>
  <button
    :disabled="image.isLoading.value"
    @click="image.generate({ prompt: 'A mountain at sunset' })"
  >
    Generate
  </button>
</template>

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. The state fields are read-only refs. Cleanup runs in onScopeDispose.

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

Realtime chat#

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

useAudioRecorder(options?)#

Records audio from the microphone. See Audio Recording.

Returns recording and isRecording (read-only refs), isSupported, start(), stop(), and cancel(). Pass onComplete to transform the recording. Then recording and stop() use the transformed type.

useByok(client)#

Subscribes to a BYOK keyring and returns a read-only ref of its snapshot. See Bring Your Own Key.

import { computed } from "vue";
import { useByok } from "@tanstack/ai-vue";
import { byok } from "./byok";

const snapshot = useByok(byok);
const last4 = computed(() => {
  const openai = snapshot.value.status.openai;
  return openai && "masked" in openai ? openai.masked : "No key";
});

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 composable. Use createMcpAppBridge, which this package re-exports. See MCP Apps.

useRegisterWebMCPTools(tools, options?)#

Exposes client tools to the browser WebMCP API for the current Vue scope. Vue removes them when the scope is disposed. See WebMCP Tools.

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

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

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

usePageWebMCPTools(options?)#

Reads the WebMCP tools that the page registered, as client tools. The ref starts empty and updates when the page adds or removes a tool. Pass the ref to useChat as tools. See Page WebMCP Tools in Chat.

import { usePageWebMCPTools } from "@tanstack/ai-vue";

export function useSameOriginPageTools() {
  return usePageWebMCPTools({
    filter: (tool) => tool.origin === location.origin,
  });
}

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

Re-exports from @tanstack/ai-client#

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

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

Types#

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