Tambo AI Documentation

Complete reference for @tambo-ai/react hooks - thread management, component state, streaming, voice, and more.

The @tambo-ai/react package provides hooks that expose state values and functions to make building AI apps with Tambo simple.

Here you'll find a description of each state value and function, organized by hook.

useTambo

The primary entrypoint for the Tambo React SDK. This hook provides access to all Tambo functionality including the client, component registry, thread context, and interactable component management.

const tambo = useTambo();

This hook returns a composite of all context values from the nested providers, including:

Client context: client, queryClient, isUpdatingToken
Thread context: thread, sendThreadMessage, generationStage, isIdle, etc.
Component context: currentMessage, currentComponent
Interactable context: interactableComponents, addInteractableComponent, etc.
Context helpers: getContextHelpers, addContextHelper, removeContextHelper
Context attachments: attachments, addContextAttachment, removeContextAttachment

For most use cases, prefer using the more specific hooks (like useTamboThread or useTamboRegistry) to access only what you need.

useTamboRegistry

This hook provides helpers for component and tool registration.

registerComponent

const { registerComponent } = useTamboRegistry()

This function is used to register components with Tambo, allowing them to be potentially used in Tambo's responses.

registerTool

const { registerTool } = useTamboRegistry()

This function is used to register tools with Tambo.

registerTools

const { registerTools } = useTamboRegistry()

This function allows registering multiple tools at once.

addToolAssociation

const { addToolAssociation } = useTamboRegistry()

This function creates an association between components and tools.

componentList

const { componentList } = useTamboRegistry()

This value provides access to the list of registered components.

toolRegistry

const { toolRegistry } = useTamboRegistry()

This value provides access to the registry of all registered tools.

componentToolAssociations

const { componentToolAssociations } = useTamboRegistry()

This value provides access to the associations between components and tools.

useTamboThread

This hook provides access to the current thread and functions for managing thread interactions.

thread

const { thread } = useTamboThread()

The current thread object containing messages and metadata. Messages can be accessed via thread.messages. This value is kept up-to-date automatically by Tambo when messages are sent or received.

sendThreadMessage

const { sendThreadMessage } = useTamboThread()

Function to send a user message to Tambo and receive a response. A call to this function will update the provided thread state value.

To have the response streamed, use sendThreadMessage(message, {streamResponse: true}).

generationStage

const { generationStage } = useTamboThread()

Current stage of message generation. Possible values are:

IDLE: The thread is not currently generating any response (Initial stage)
CHOOSING_COMPONENT: Tambo is determining which component to use for the response
FETCHING_CONTEXT: Gathering necessary context for the response by calling a registered tool
HYDRATING_COMPONENT: Generating the props for a chosen component
STREAMING_RESPONSE: Actively streaming the response
COMPLETE: Generation process has finished successfully
ERROR: An error occurred during the generation process

inputValue

const { inputValue } = useTamboThread()

Current value of the thread input field.

generationStatusMessage

const { generationStatusMessage } = useTamboThread()

Status message describing the current generation state, as generated by Tambo.

isIdle

const { isIdle } = useTamboThread()

Boolean indicating whether the thread is in an idle state (generationStage is IDLE, COMPLETE, or ERROR).

switchCurrentThread

const { switchCurrentThread } = useTamboThread()

Function to change the active thread by id. This will update the thread state value to the fetched thread.

addThreadMessage

const { addThreadMessage } = useTamboThread()

Function to append a new message to the thread.

updateThreadMessage

const { updateThreadMessage } = useTamboThread()

Function to modify an existing thread message.

setLastThreadStatus

const { setLastThreadStatus } = useTamboThread()

Function to update the status of the most recent thread message.

setInputValue

const { setInputValue } = useTamboThread()

Function to update the input field value.

useTamboThreadList

This hook provides access to the list of all threads for a project and their loading states.

data

const { data } = useTamboThreadList()

Array of threads or null if not yet loaded.

isPending

const { isPending } = useTamboThreadList()

Boolean indicating if threads are currently being fetched.

isSuccess

const { isSuccess } = useTamboThreadList()

Boolean indicating if threads were successfully fetched.

isError

const { isError } = useTamboThreadList()

Boolean indicating if an error occurred while fetching threads.

error

const { error } = useTamboThreadList()

Error object containing details if the fetch failed.

useTamboThreadInput

This hook provides utilities for building an input interface that sends messages to Tambo.

value

const { value } = useTamboThreadInput()

Current value of the input field.

setValue

const { setValue } = useTamboThreadInput()

Function to update the input field value.

submit

const { submit } = useTamboThreadInput()

Function to submit the current input value, with optional context and streaming configuration.

isPending

const { isPending } = useTamboThreadInput()

Boolean indicating if a submission is in progress.

isSuccess

const { isSuccess } = useTamboThreadInput()

Boolean indicating if the last submission was successful.

isError

const { isError } = useTamboThreadInput()

Boolean indicating if the last submission failed.

error

const { error } = useTamboThreadInput()

Error object containing details if the submission failed.

useTamboSuggestions

This hook provides utilities for managing AI-generated message suggestions.

suggestions

const { suggestions } = useTamboSuggestions()

List of available AI-generated suggestions for the next message.

selectedSuggestionId

const { selectedSuggestionId } = useTamboSuggestions()

ID of the currently selected suggestion.

accept

const { accept } = useTamboSuggestions()

Function to accept and apply a suggestion, with an option for automatic submission.

acceptResult

const { acceptResult } = useTamboSuggestions()

Detailed mutation result for accepting a suggestion.

generateResult

const { generateResult } = useTamboSuggestions()

Detailed mutation result for generating new suggestions.

isPending

const { isPending } = useTamboSuggestions()

Boolean indicating if a suggestion operation is in progress.

isSuccess

const { isSuccess } = useTamboSuggestions()

Boolean indicating if the last operation was successful.

isError

const { isError } = useTamboSuggestions()

Boolean indicating if the last operation resulted in an error.

error

const { error } = useTamboSuggestions()

Error object containing details if the operation failed.

useTamboClient

This hook provides direct access to the Tambo client instance.

client

const { client } = useTamboClient()

The Tambo client instance for direct API access.

useTamboComponentState

This hook is similar to React's useState, but allows Tambo to see the state values to help respond to later messages.

const [myValue, setMyValue] = useTamboComponentState(keyName, initialValue, setFromProp)

For streaming components, use the third parameter (setFromProp) to seed editable state from AI-generated props. Combined with useTamboStreamStatus, this lets you disable inputs while streaming and hand control to the user once complete.

value and setValue

const { value } = useTamboComponentState()

Current state value stored in the thread message for the given key.

setValue

const { setValue } = useTamboComponentState()

Function to update the state value, synchronizing both local state and server state.

useTamboContextHelpers

This hook provides dynamic control over context helpers.

getContextHelpers

const { getContextHelpers } = useTamboContextHelpers()

Returns the current map of registered helper functions keyed by name.

addContextHelper

const { addContextHelper } = useTamboContextHelpers()

Adds or replaces a helper at the given key.

removeContextHelper

const { removeContextHelper } = useTamboContextHelpers()

Removes a helper by key so it is no longer included in outgoing messages.

useTamboContextAttachment

This hook provides utilities for managing context attachments that will be sent with the next user message.

attachments

const { attachments } = useTamboContextAttachment()

Array of active context attachments that will be included in additionalContext when the next message is sent.

addContextAttachment

const { addContextAttachment } = useTamboContextAttachment()

Function to add a new context attachment. Accepts an object with context (string), optional displayName (string), and optional type (string). Returns the ContextAttachment object with an auto-generated id. All attachments are automatically registered together as a single merged context helper (key: contextAttachments) that returns an array of all active attachments.

// Without displayName
const attachment = addContextAttachment({
  context: "The contents of File.txt",
});

// With displayName
const attachment = addContextAttachment({
  context: "The contents of File.txt",
  displayName: "File.txt",
});

// With displayName and type
const attachment = addContextAttachment({
  context: "The contents of File.txt",
  displayName: "File.txt",
  type: "file",
});

removeContextAttachment

const { removeContextAttachment } = useTamboContextAttachment()

Function to remove a specific context attachment by its ID. The context helper automatically updates to reflect the change.

clearContextAttachments

const { clearContextAttachments } = useTamboContextAttachment()

Function to remove all active context attachments at once. The context helper automatically updates to reflect the change. Context attachments are automatically cleared after message submission (one-time use), so you typically don't need to call this manually.

useCurrentInteractablesSnapshot

const snapshot = useCurrentInteractablesSnapshot()

Returns a cloned snapshot of the current interactable components.

useTamboCurrentMessage

const message = useTamboCurrentMessage()

Returns the complete TamboThreadMessage object for the current message, including thread ID, component data, state, and timestamps. Must be used within a component rendered as part of a message thread.

Use when you need full message/thread context. For component metadata only, see useTamboCurrentComponent.

useTamboCurrentComponent

const component = useTamboCurrentComponent()

Returns component metadata (componentName, props, interactableId, description, threadId) from the parent component context. Returns null if used outside a component. Works with both inline rendered and interactable components.

Use when you need component information or thread ID without full message context. For complete message data, see useTamboCurrentMessage.

See Interactable Components for detailed patterns and examples.

useTamboStreamStatus

Track streaming status for Tambo component props. Returns both global stream status and per-prop status flags.

const { streamStatus, propStatus } = useTamboStreamStatus<Props>();

Important: Props update repeatedly during streaming and may be partial. Use propStatus.<field>?.isSuccess before treating a prop as complete.

streamStatus

Global stream status flags for the component:

interface StreamStatus {
  isPending: boolean; // No tokens received yet, generation not active
  isStreaming: boolean; // Active streaming - generation or props still streaming
  isSuccess: boolean; // Complete - all props finished without error
  isError: boolean; // Fatal error occurred
  streamError?: Error; // First error encountered (if any)
}

propStatus

Per-prop streaming status:

interface PropStatus {
  isPending: boolean; // No tokens received for this prop yet
  isStreaming: boolean; // Prop has partial content, still updating
  isSuccess: boolean; // Prop finished streaming successfully
  error?: Error; // Error during streaming (if any)
}

Example: Wait for entire stream

const { streamStatus } = useTamboStreamStatus();

if (!streamStatus.isSuccess) {
  return <Spinner />;
}

return <Card {...props} />;

Example: Highlight in-flight props

const { propStatus } = useTamboStreamStatus<Props>();

return (
  <h2 className={propStatus.title?.isStreaming ? "animate-pulse" : ""}>
    {title}
  </h2>
);

useTamboStreamingProps

Deprecated: Use useTamboComponentState with setFromProp instead. This hook will be removed in 1.0.0.

Low-level helper that merges streamed props into state.

useTamboStreamingProps(currentState, setState, streamingProps);

useTamboGenerationStage

Access the current generation stage from the thread context.

const { generationStage } = useTamboGenerationStage();

Returns the current GenerationStage enum value. See GenerationStage for possible values.

useTamboVoice

Exposes functionality to record speech and transcribe it using the Tambo API.

const {
  startRecording,
  stopRecording,
  isRecording,
  isTranscribing,
  transcript,
  transcriptionError,
  mediaAccessError,
} = useTamboVoice();

Return values

Value	Type	Description
`startRecording`	`() => void`	Start recording audio and reset the current transcript
`stopRecording`	`() => void`	Stop recording and automatically start transcription
`isRecording`	`boolean`	Whether the user is currently recording
`isTranscribing`	`boolean`	Whether audio is being transcribed
`transcript`	`string \| null`	The transcript of the recorded audio
`transcriptionError`	`string \| null`	Error message if transcription fails
`mediaAccessError`	`string \| null`	Error message if microphone access fails

Example

function VoiceInput() {
  const {
    startRecording,
    stopRecording,
    isRecording,
    isTranscribing,
    transcript,
  } = useTamboVoice();

  return (
    <div>
      <button onClick={isRecording ? stopRecording : startRecording}>
        {isRecording ? "Stop" : "Record"}
      </button>
      {isTranscribing && <span>Transcribing...</span>}
      {transcript && <p>{transcript}</p>}
    </div>
  );
}

useTamboInteractable

Provides access to the interactable component management functions.

const {
  interactableComponents,
  addInteractableComponent,
  removeInteractableComponent,
  updateInteractableComponentProps,
  getInteractableComponent,
  getInteractableComponentsByName,
  clearAllInteractableComponents,
  setInteractableState,
  getInteractableComponentState,
  setInteractableSelected,
  clearInteractableSelections,
} = useTamboInteractable();

const { images, addImage, addImages, removeImage, clearImages } =
  useMessageImages();

React SDK Hooks

On this page