# React SDK Hooks URL: /reference/react-sdk-legacy/hooks 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. ```tsx 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. ```tsx // 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). ## 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`](#usetambocurrentmessage). See [Interactable Components](/concepts/generative-interfaces/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. ```tsx const { streamStatus, propStatus } = useTamboStreamStatus(); ``` **Important**: Props update repeatedly during streaming and may be partial. Use `propStatus.?.isSuccess` before treating a prop as complete. ### streamStatus Global stream status flags for the component: ```tsx 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: ```tsx 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 ```tsx const { streamStatus } = useTamboStreamStatus(); if (!streamStatus.isSuccess) { return ; } return ; ``` ### Example: Highlight in-flight props ```tsx const { propStatus } = useTamboStreamStatus(); return (

{title}

); ``` ## 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. ```tsx useTamboStreamingProps(currentState, setState, streamingProps); ``` ## useTamboGenerationStage Access the current generation stage from the thread context. ```tsx const { generationStage } = useTamboGenerationStage(); ``` Returns the current `GenerationStage` enum value. See [GenerationStage](/reference/react-sdk/types#generationstage) for possible values. ## useTamboVoice Exposes functionality to record speech and transcribe it using the Tambo API. ```tsx 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 ```tsx function VoiceInput() { const { startRecording, stopRecording, isRecording, isTranscribing, transcript, } = useTamboVoice(); return (
{isTranscribing && Transcribing...} {transcript &&

{transcript}

}
); } ``` ## useTamboInteractable Provides access to the interactable component management functions. ```tsx const { interactableComponents, addInteractableComponent, removeInteractableComponent, updateInteractableComponentProps, getInteractableComponent, getInteractableComponentsByName, clearAllInteractableComponents, setInteractableState, getInteractableComponentState, setInteractableSelected, clearInteractableSelections, } = useTamboInteractable(); ``` ### interactableComponents `TamboInteractableComponent[]` - Array of currently registered interactable components. ### addInteractableComponent `(component: Omit) => string` Registers a new interactable component. Returns the generated component ID. ### removeInteractableComponent `(id: string) => void` Removes an interactable component by ID. ### updateInteractableComponentProps `(id: string, newProps: Record) => string` Updates the props of an interactable component. Returns a status message. ### getInteractableComponent `(id: string) => TamboInteractableComponent | undefined` Gets a specific interactable component by ID. ### getInteractableComponentsByName `(componentName: string) => TamboInteractableComponent[]` Gets all interactable components with the given name. ### clearAllInteractableComponents `() => void` Removes all interactable components. ### setInteractableState `(componentId: string, key: string, value: unknown) => void` Sets a specific state value for an interactable component. ### getInteractableComponentState `(componentId: string) => Record | undefined` Gets the current state of an interactable component. ### setInteractableSelected `(componentId: string, isSelected: boolean) => void` Sets the selected state of an interactable component. ### clearInteractableSelections `() => void` Clears all component selections. ## useMessageImages Hook for managing images in message input. ```tsx const { images, addImage, addImages, removeImage, clearImages } = useMessageImages(); ``` ### images `StagedImage[]` - Array of staged images ready to be sent with a message. ### addImage `(file: File) => Promise` Add a single image file. Throws if the file is not an image. ### addImages `(files: File[]) => Promise` Add multiple image files. Only valid image files will be added. ### removeImage `(id: string) => void` Remove a staged image by ID. ### clearImages `() => void` Remove all staged images.