# Complete Guide to Tambo AI Hooks for Managing AI Interactions

> Explore Tambo AI hooks for seamless AI interaction management. Discover 15+ React hooks like useTambo, useTamboSendMessage, and useTamboThread for auth, threads, streaming, and UI state.

- Repository: [tambo ai/tambo](https://github.com/tambo-ai/tambo)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/tambo-ai/tambo/blob/main/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.

```typescript
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`](https://github.com/tambo-ai/tambo/blob/main/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.

```typescript
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`](https://github.com/tambo-ai/tambo/blob/main/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.

```typescript
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`](https://github.com/tambo-ai/tambo/blob/main/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.

```typescript
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`](https://github.com/tambo-ai/tambo/blob/main/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.

```typescript
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`](https://github.com/tambo-ai/tambo/blob/main/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.

```typescript
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`](https://github.com/tambo-ai/tambo/blob/main/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.

```typescript
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`](https://github.com/tambo-ai/tambo/blob/main/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.

```typescript
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`](https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/hooks/use-message-images.ts). This helper hook processes message content to extract and validate image URLs for rendering.

```typescript
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`](https://github.com/tambo-ai/tambo/blob/main/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.

```typescript
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`](https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/hooks/react-query-hooks.ts). These thin wrappers around TanStack React Query ensure consistent caching and error handling.

```typescript
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`](https://github.com/tambo-ai/tambo/blob/main/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`](https://github.com/tambo-ai/tambo/blob/main/use-tambo-v1-thread.ts) and [`use-tambo-v1-thread-list.ts`](https://github.com/tambo-ai/tambo/blob/main/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`](https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/v1/hooks/use-tambo-v1.ts). **`useTamboThread`**, located in [`react-sdk/src/v1/hooks/use-tambo-v1-thread.ts`](https://github.com/tambo-ai/tambo/blob/main/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`](https://github.com/tambo-ai/tambo/blob/main/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`](https://github.com/tambo-ai/tambo/blob/main/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.