Complete Guide to Tambo AI Hooks for Managing AI Interactions

The @tambo-ai/react SDK provides 15+ specialized React hooks—including useTambo, useTamboSendMessage, and useTamboThread—that handle authentication, thread management, message streaming, and AI-driven UI state without manual API calls.

The Tambo AI React SDK abstracts complex AI interaction patterns into a declarative, type-safe hook-based API. Whether you're building chat interfaces, managing conversation threads, or rendering AI-generated components, these hooks—built on React Context and TanStack React Query—provide automatic caching, error handling, and streaming lifecycle management. This guide covers every hook available in the SDK, their specific file locations, and practical implementation patterns.

Core Thread Management Hooks

useTambo

The useTambo hook serves as the primary entry point for the entire SDK. Located in react-sdk/src/v1/hooks/use-tambo-v1.ts, it aggregates all core contexts into a single interface, exposing the Tambo client, current thread state, message arrays, streaming status, component and tool registries, authentication state, and thread-control helpers.

import { useTambo } from "@tambo-ai/react";

function App() {
  const { 
    client, 
    currentThreadId, 
    messages, 
    streamingState,
    registerComponent,
    registerTool 
  } = useTambo();
  
  // Access to all SDK functionality
}

useTamboThread

For fetching a specific conversation thread with React Query caching, use useTamboThread. This hook, defined in react-sdk/src/v1/hooks/use-tambo-v1-thread.ts, retrieves a single thread including its messages and run status, with automatic background refetching and stale-time control.

import { useTamboThread } from "@tambo-ai/react";

function ThreadView({ threadId }: { threadId: string }) {
  const { data: thread, isLoading, error } = useTamboThread(threadId);
  
  if (isLoading) return <div>Loading thread...</div>;
  if (error) return <div>Error loading thread</div>;
  
  return <MessageList messages={thread.messages} />;
}

useTamboThreadList

To retrieve a paginated list of a user's threads, use useTamboThreadList from react-sdk/src/v1/hooks/use-tambo-v1-thread-list.ts. This hook provides caching and stale-time control for thread listing interfaces, enabling conversation history browsers.

import { useTamboThreadList } from "@tambo-ai/react";

function ThreadHistory() {
  const { data: threads, fetchNextPage, hasNextPage } = useTamboThreadList();
  
  return (
    <div>
      {threads?.pages.map(page => 
        page.threads.map(thread => (
          <ThreadCard key={thread.id} thread={thread} />
        ))
      )}
      {hasNextPage && <button onClick={() => fetchNextPage()}>Load more</button>}
    </div>
  );
}

Message Handling and Streaming Hooks

useTamboSendMessage

The useTamboSendMessage hook, located in react-sdk/src/v1/hooks/use-tambo-v1-send-message.ts, is the primary mutation hook for sending messages. It handles posting user messages, streaming AI responses, executing tools, and optionally auto-generating thread names based on conversation content.

import { useTamboSendMessage } from "@tambo-ai/react";

function ChatInput({ threadId }: { threadId: string }) {
  const sendMessage = useTamboSendMessage(threadId);
  
  const handleSubmit = async (text: string) => {
    await sendMessage.mutateAsync({
      message: { 
        role: "user", 
        content: [{ type: "text", text }] 
      },
      userMessageText: text, // for optimistic UI updates
    });
  };
  
  return (
    <form onSubmit={(e) => {
      e.preventDefault();
      const text = e.currentTarget.message.value;
      handleSubmit(text);
      e.currentTarget.reset();
    }}>
      <input name="message" disabled={sendMessage.isPending} />
      <button type="submit" disabled={sendMessage.isPending}>
        {sendMessage.isPending ? "Sending..." : "Send"}
      </button>
    </form>
  );
}

useTamboMessages

For simple access to the current thread's message array, use useTamboMessages from react-sdk/src/v1/hooks/use-tambo-v1-messages.ts. This is a convenience wrapper derived from useTambo that returns the processed message array, already enriched with rendered components and tool-status metadata.

import { useTamboMessages } from "@tambo-ai/react";

function MessageList() {
  const messages = useTamboMessages();
  
  return (
    <div className="message-list">
      {messages.map((message) => (
        <MessageBubble 
          key={message.id} 
          content={message.content}
          components={message.renderedComponents}
        />
      ))}
    </div>
  );
}

useTamboThreadInput

To manage the chat input field state and suggestion triggers, use useTamboThreadInput from react-sdk/src/v1/hooks/use-tambo-v1-thread-input.ts. This hook provides the current input value, a setter, and methods to trigger input suggestions.

import { useTamboThreadInput } from "@tambo-ai/react";

function SuggestionInput() {
  const { input, setInput, triggerSuggestion } = useTamboThreadInput();
  
  return (
    <div>
      <input 
        value={input} 
        onChange={(e) => setInput(e.target.value)}
        placeholder="Type your message..."
      />
      <button onClick={triggerSuggestion} disabled={!input}>
        Get Suggestions
      </button>
    </div>
  );
}

UI State and Lifecycle Hooks

useTamboComponentState

For managing AI-driven component state that persists across renders, use useTamboComponentState from react-sdk/src/v1/hooks/use-tambo-v1-component-state.ts. This hook provides a stable state object, a setter function, and an isPending flag for handling asynchronous state updates.

import { useTamboComponentState } from "@tambo-ai/react";

function AICounter({ initial = 0 }: { initial?: number }) {
  const [count, setCount, { isPending }] = useTamboComponentState(
    "counter-state",
    { value: initial }
  );

  return (
    <div>
      <p>Current Count: {count?.value ?? initial}</p>
      <button 
        onClick={() => setCount({ value: (count?.value ?? 0) + 1 })} 
        disabled={isPending}
      >
        Increment
      </button>
    </div>
  );
}

useTamboStreamStatus

To monitor the low-level streaming lifecycle, use useTamboStreamStatus from react-sdk/src/v1/hooks/use-tambo-v1-stream-status.ts. This hook exposes the streaming state as one of three values: idle, waiting, or streaming, enabling UI feedback like loading indicators and input disabling.

import { useTamboStreamStatus } from "@tambo-ai/react";

function StreamingIndicator() {
  const status = useTamboStreamStatus();
  
  if (status === "streaming") {
    return <div className="typing-indicator">AI is thinking...</div>;
  }
  
  if (status === "waiting") {
    return <div className="spinner">Loading...</div>;
  }
  
  return null;
}

useMessageImages

For resolving image URLs embedded in message content, use useMessageImages from react-sdk/src/hooks/use-message-images.ts. This helper hook processes message content to extract and validate image URLs for rendering.

import { useMessageImages } from "@tambo-ai/react";

function MessageWithImages({ message }) {
  const imageUrls = useMessageImages(message);
  
  return (
    <div className="message">
      <p>{message.text}</p>
      {imageUrls.map((url, index) => (
        <img key={index} src={url} alt="Message attachment" />
      ))}
    </div>
  );
}

Authentication and Data Fetching Hooks

useTamboAuthState

Monitor authentication status using useTamboAuthState from react-sdk/src/v1/hooks/use-tambo-v1-auth-state.ts. This hook surfaces the current auth state—such as identified, exchanging, or error—allowing you to gate features until the SDK is ready.

import { useTamboAuthState } from "@tambo-ai/react";

function AuthenticatedApp() {
  const authState = useTamboAuthState();
  
  if (authState.status !== "identified") {
    return <div>Authenticating...</div>;
  }
  
  return <ChatInterface />;
}

useTamboQuery, useTamboMutation, and useTamboQueries

For custom data fetching that respects the SDK's internal QueryClient and authentication configuration, use the React Query wrapper hooks from react-sdk/src/hooks/react-query-hooks.ts. These thin wrappers around TanStack React Query ensure consistent caching and error handling.

import { useTamboQuery } from "@tambo-ai/react";

function CustomAnalytics() {
  const { data, isLoading } = useTamboQuery({
    queryKey: ["analytics", "usage"],
    queryFn: async () => {
      // Custom fetch that uses the authenticated client
      const response = await fetch("/api/custom-analytics");
      return response.json();
    },
  });
  
  if (isLoading) return <div>Loading analytics...</div>;
  return <AnalyticsDashboard data={data} />;
}

Hook Integration Patterns

Understanding how these Tambo AI hooks work together is essential for building robust applications. The typical workflow follows this sequence:

1. Authentication: useTamboAuthState confirms the SDK is ready (identified status) before initiating AI interactions.

2. Thread Selection: Use useTamboThread to fetch an existing conversation or useTambo to access the current thread ID.

3. Message Flow: useTamboSendMessage handles the complete message lifecycle—posting user input, streaming AI responses, and executing tools—while useTamboStreamStatus provides real-time feedback on the streaming state (idle | waiting | streaming).

4. Component Registration: Through useTambo, call registerComponent to expose React components that the AI can dynamically render during conversations.

5. State Persistence: For components that need to maintain state across AI interactions, useTamboComponentState provides persistent storage with pending states.

Summary

The Tambo AI React SDK delivers a comprehensive hook-based architecture for managing AI interactions:

• useTambo acts as the central hub, exposing client methods, registries, and thread state from react-sdk/src/v1/hooks/use-tambo-v1.ts.
• Thread management hooks (useTamboThread, useTamboThreadList) provide cached access to conversation history via files like use-tambo-v1-thread.ts and use-tambo-v1-thread-list.ts.
• Message handling hooks (useTamboSendMessage, useTamboMessages, useTamboThreadInput) streamline sending messages, accessing conversation history, and managing input fields.
• Lifecycle and state hooks (useTamboStreamStatus, useTamboComponentState, useTamboAuthState) monitor streaming states, persist component data, and track authentication.
• Utility hooks (useMessageImages, useTamboQuery) handle image resolution and custom data fetching within the SDK's authenticated context.

Together, these hooks eliminate boilerplate networking code while providing type-safe, cached, and reactive AI interaction management.

Frequently Asked Questions

What is the difference between useTambo and useTamboThread?

useTambo is the global SDK entry point that provides access to the Tambo client, current thread ID, and registration methods for components and tools. It lives in react-sdk/src/v1/hooks/use-tambo-v1.ts. useTamboThread, located in react-sdk/src/v1/hooks/use-tambo-v1-thread.ts, is a React Query-powered hook specifically for fetching a single thread's data (messages, metadata, run status) with automatic caching and background updates. Use useTambo for global SDK operations and useTamboThread when you need detailed thread data fetching.

How do I know when the AI is actively streaming a response?

Use the useTamboStreamStatus hook from react-sdk/src/v1/hooks/use-tambo-v1-stream-status.ts. This hook returns one of three states: idle (no active stream), waiting (request sent, awaiting first token), or streaming (actively receiving AI response chunks). Combine this with useTamboSendMessage to disable input fields or show typing indicators while the status is streaming or waiting.

Can I use Tambo AI hooks with my own React Query configuration?

Yes, through the useTamboQuery, useTamboMutation, and useTamboQueries hooks exported from react-sdk/src/hooks/react-query-hooks.ts. These are thin wrappers around TanStack React Query that automatically use the SDK's internal QueryClient and respect its authentication configuration. This ensures your custom data fetching shares the same caching layer and auth headers as the core Tambo AI hooks, maintaining consistency across your application.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}