Loading...
;
}
```
```tsx
if (error) {
return ` object, allowing you to pass any structured data as context.
#### Context Helpers
Tambo can automatically include context helpers with every message when they are configured. Configure helpers either:
* Globally on `TamboProvider` via the `contextHelpers` prop, or
* Locally on a page/layout using `TamboContextHelpersProvider` (active only while mounted)
**Prebuilt helpers include:**
* **currentTimeContextHelper**: Returns current timestamp
* **currentPageContextHelper**: Returns current page URL/title information
You can also define custom context helpers and register them either globally with `TamboProvider` or locally with `TamboContextHelpersProvider`. Any active helpers will be automatically merged into the message context. If the same key is registered in multiple places at different times, the most recently mounted registration takes precedence while it’s mounted.
Learn more about additionalContext.
Your manual `additionalContext` will be merged with any resolved helper results. For example, if the `currentTimeContextHelper` context helper is passed, the above code would result in a combined context like:
```json
{
"pageInfo": {
"url": "/weather"
},
"location": "San Francisco",
"units": "fahrenheit",
"userTime": {
"timestamp": "2025-01-15T20:30:00.000Z"
}
}
```
# Showing Responses
URL: /concepts/message-threads/showing-responses
### Showing thread messages and components
Since tambo keeps the thread state updated, all you need to do is show the thread's messages somewhere. If a message from tambo includes a component, it can be accessed with `message.renderedComponent`:
```tsx
const { thread } = useTamboThread()
...
thread.messages.map((message) => (
Sent by: {message.role}
message text: {message.content[0]?.text}
component: {message.renderedComponent}
))
```
For canvas-style UIs where you want to display only the most recent component, you can walk backwards through the messages to find the latest one with a `renderedComponent`:
```tsx
const latestComponent = thread.messages
.slice()
.reverse()
.find((message) => message.renderedComponent)?.renderedComponent;
...
{latestComponent}
```
This approach is useful for building interactive canvases, dashboards, or any UI where you want to show the most up-to-date component state without displaying the full conversation history.
# Switching Thread
URL: /concepts/message-threads/switching-thread
### Setting the current thread
By default, tambo will create a new thread for you and use that thread for the `thread` state value.
If you want to switch to another thread you can use the `switchCurrentThread` function:
```tsx
const { switchCurrentThread } = useTamboThread()
...
switchCurrentThread(threadId)
```
The `thread` state will be updated, and anywhere you are rendering the threads list of messages will now be showing the new thread's messages!
# Tracking Response Stage
URL: /concepts/message-threads/thread-status
You may want to show your users something unique during each stage of tambo's response generation process, rather than a static 'loading' message for the entire duration.
To enable this, each thread has a `generationStage` property that can be used to track the progress of the response generation process.
You can expose the generation stage ( or a value you derive from it ) to your users so they know what their AI assistant is doing.
```typescript title="generation-stage.tsx"
const { generationStage } = useTamboThread();
...
if (generationStage === GenerationStage.CHOOSING_COMPONENT) {
return Tambo is choosing the best component to use...
;
}
if (generationStage === GenerationStage.FETCHING_CONTEXT) {
return Tambo is fetching additional data to hydrate the component...
;
}
...
```
### Stages
A thread's generation stage is an enum with the following possible values:
```typescript title="generation stages"
enum GenerationStage {
IDLE = "IDLE", // The thread is idle ( initial stage )
CHOOSING_COMPONENT = "CHOOSING_COMPONENT", // Tambo is choosing the best component to use based on the user's message
FETCHING_CONTEXT = "FETCHING_CONTEXT", // Tambo is fetching additional data to hydrate a chosen component
HYDRATING_COMPONENT = "HYDRATING_COMPONENT", // Tambo is hydrating the component
STREAMING_RESPONSE = "STREAMING_RESPONSE", // Tambo is streaming the response
COMPLETE = "COMPLETE", // Tambo has completed successfully
ERROR = "ERROR", // Tambo has encountered an error
CANCELLED = "CANCELLED", // The latest message generation was cancelled.
}
```
### Status Message
Instead of determining a custom message for each stage, you can use the `statusMessage` property, which is a context-aware string that describes the current stage of the generation process, as generated by Tambo.
For example, if the generation was triggered by a user message asking about the weather in Tokyo, during the `CHOOSING_COMPONENT` stage the `statusMessage` might be something like `"Looking for a component to help with your request about the weather in Tokyo"`.
Use this along with the `isProcessing` helper property which returns `true` if the `generationStage` is `CHOOSING_COMPONENT`, `FETCHING_CONTEXT`, `HYDRATING_COMPONENT`, or `STREAMING_RESPONSE`.
```typescript title="generation-stage.tsx"
const { statusMessage, isProcessing } = useTamboThread();
if (isProcessing) {
return {statusMessage}
;
}
```
# Model Context Protocol (MCP)
URL: /concepts/model-context-protocol
Model Context Protocol (MCP) allows you to give Tambo access to tools defined by other people. Many popular services publish MCP servers, and Tambo provides a simple way to connect to them. This is a quick way to allow your users to conversationally interact with other services without needing to write any of the interaction code yourself.
## Connection Types
Tambo supports two ways to connect to MCP servers:
1. **[Server-side MCP](/concepts/model-context-protocol/providers/serverside-mcp-connection)** (recommended) - Configure MCP servers through the Tambo dashboard. Best for shared services, OAuth authentication, and optimal performance.
2. **[Client-side MCP](/concepts/model-context-protocol/providers/clientside-mcp-connection)** - Connect directly from the browser to MCP servers accessible to end users. Best for local servers and user-specific services.
## Quick Start
```tsx
```
# Component Streaming Status
URL: /concepts/streaming/component-streaming-status
The `useTamboStreamStatus` hook lets you track both overall and per-prop streaming status, so you can show loading or completed states for each prop as they arrive.
## How Does It Work?
Without per-prop tracking, you're forced to show nothing until all props are ready (poor UX) or show everything with default values (potentially confusing). This hook gives you granular control over what renders when.
```tsx title="basic-usage.tsx"
import { useTamboStreamStatus } from "@tambo-ai/react";
function Note({ title, content, createdAt }) {
const { streamStatus, propStatus } = useTamboStreamStatus();
// Wait for everything to complete
if (!streamStatus.isSuccess) return ;
return (
{title}
{content}
{propStatus["createdAt"]?.isSuccess &&
{createdAt}
}
);
}
```
This guide builds on **[Streaming](/concepts/streaming)** and **[Response
Component Streaming](/concepts/streaming/response-component-streaming)**. We
recommend reading those first.
## Status Types
### Global Stream Status (`streamStatus`)
Tracks the overall state of the entire component:
| Field | Type | Description |
| -------------- | --------- | -------------------------------------------------------- |
| `isPending` | `boolean` | No tokens received yet, show initial loading state |
| `isStreaming` | `boolean` | Active data transmission (generation OR props streaming) |
| `isSuccess` | `boolean` | All props completed successfully |
| `isError` | `boolean` | Any fatal error occurred in generation or props |
| `streamError?` | `Error` | First error encountered during streaming |
### Per-Prop Status (`propStatus`)
Tracks individual prop streaming states:
| Field | Type | Description |
| ------------- | --------- | ------------------------------------------------- |
| `isPending` | `boolean` | No tokens received for this specific prop yet |
| `isStreaming` | `boolean` | Partial content received, prop is still updating |
| `isSuccess` | `boolean` | Prop finished streaming successfully |
| `error?` | `Error` | Error that occurred during streaming of this prop |
## Usage Patterns
### Wait for Everything to Complete
```tsx title="wait-for-all.tsx"
function ArticleCard({ title, content, author }) {
const { streamStatus } = useTamboStreamStatus();
if (streamStatus.isPending) return ;
if (streamStatus.isError)
return Error: {streamStatus.streamError?.message}
;
if (!streamStatus.isSuccess) return ;
return (
{title}
{content}
By {author}
);
}
```
### Progressive Rendering
Show each prop as it becomes available:
```tsx title="progressive-rendering.tsx"
function DashboardWidget({ title, data, config }) {
const { propStatus } = useTamboStreamStatus();
return (
{propStatus["title"]?.isPending &&
}
{propStatus["title"]?.isSuccess &&
{title}
}
{propStatus["data"]?.isStreaming &&
}
{propStatus["data"]?.isSuccess &&
}
{propStatus["config"]?.isSuccess &&
}
{content}
{/* Handle errors gracefully */}
{propStatus["tags"]?.error && Failed to load tags
}
{propStatus["tags"]?.isSuccess && (
{tags.map((tag) => (
{tag}
))}
)}
);
}
```
## When to Use Component Streaming Status
**✅ Use When**
* Different props have different loading times
* You want progressive rendering
* You need fine-grained error handling
* You have complex UI that depends on multiple props
**❌ Don't Use When**
* You only have simple text content
* You're doing SSR/SSG (client-side only)
## Integration with Other Tambo Features
### With Stream Status Provider
```tsx title="with-provider.tsx"
import { TamboPropStreamProvider, useTamboStreamStatus } from "@tambo-ai/react";
function EnhancedComponent({ title, content, metadata }) {
const { streamStatus } = useTamboStreamStatus();
return (
{title}
{content}
);
}
```
The **[Stream Status
Provider](/concepts/streaming/tambo-prop-stream-provider)** provides
declarative streaming state management with built-in loading and complete
states for individual props.
### With Streaming Props Hook
```tsx title="with-streaming-props.tsx"
import { useTamboStreamingProps, useTamboStreamStatus } from "@tambo-ai/react";
function StatefulComponent({ streamedTitle, streamedContent }) {
const { propStatus } = useTamboStreamStatus();
const [state, setState] = useState({ title: "", content: "" });
useTamboStreamingProps(state, setState, {
title: streamedTitle,
content: streamedContent,
});
return (
{state.title}
{propStatus["content"]?.isSuccess &&
{state.content}
}
);
}
```
The **[Streaming Props into State](/concepts/streaming/streaming-props)**
feature allows you to automatically update component state as props stream in,
providing seamless integration with React state management.
# Streaming
URL: /concepts/streaming
Tambo allows you to show response messages and components in real-time as they are being generated, creating more responsive and engaging user experiences. Instead of waiting for the entire response to complete, Tambo handles updating the thread's final message as data streams in, allowing your users to see content appear progressively. This is especially useful for longer responses or when components need to be populated with data that arrives incrementally.
# Response Component Streaming
URL: /concepts/streaming/response-component-streaming
When you `message.renderedComponent` is called, it will return a component and it will update the props as the values stream in.
## How Does It Work?
Inside the provider the `thread.messages` array is updated with the `renderedComponent` property.
```tsx title="basic-streaming.tsx"
import { useTambo } from "@tambo-ai/react";
function ChatInterface() {
const { thread } = useTambo();
return (
{thread.messages.map((message, index) => (
{/* Updates in real-time as props stream in */}
{message.renderedComponent}
))}
{title}
{content}
By {author}
);
};
```
### 2. Optional Props with Conditional Rendering
```tsx title="optional-props.tsx"
const WeatherWidget = ({
temperature,
condition,
humidity,
}: {
temperature?: number;
condition?: string;
humidity?: number;
}) => {
return (
{temperature !== undefined ? `${temperature}°C` : "Loading..."}
{condition || "Loading condition..."}
{humidity !== undefined ? `${humidity}%` : "Loading humidity..."}
);
};
```
**Important**: If your component uses objects with internal state (like form
controls, charts, or complex UI components), use `useEffect` or the **[Stream
Status Provider](/concepts/streaming/tambo-prop-stream-provider)** to properly
handle state updates as props stream in.
# Response Text Streaming
URL: /concepts/streaming/response-text-streaming
When you send a message to Tambo, Tambo will handle updating the thread's final message as data streams in rather than waiting for the entire response to complete.
Send a message to the current thread:
```tsx title="streaming.tsx"
import { useTambo } from "@tambo-ai/react";
const { sendThreadMessage } = useTambo();
await sendThreadMessage(inputValue);
//or
const { submit } = useTamboThreadInput();
await submit();
```
Render your thread messages like normal.
```tsx title="streaming.tsx"
import { useTambo } from "@tambo-ai/react";
const { thread } = useTambo();
...
{thread.messages.map((message, index) => (
{message.content[0].text}
))}
{state?.title}
{state?.body}
);
}
```
## Benefits
* Eliminates repetitive useEffect code
* Automatically detects and applies changes
* Only updates when values actually change
* Works with any state shape
* Type-safe with TypeScript
## Without vs With
**Before (repetitive pattern):**
```tsx
useEffect(() => {
if (state) {
const shouldUpdateTitle = streamedTitle && streamedTitle !== state.title;
const shouldUpdateBody = streamedBody && streamedBody !== state.body;
if (shouldUpdateTitle || shouldUpdateBody) {
setState({
...state,
title: shouldUpdateTitle ? streamedTitle : state.title,
body: shouldUpdateBody ? streamedBody : state.body,
});
}
}
}, [streamedTitle, streamedBody]);
```
**After (clean and simple):**
```tsx
useTamboStreamingProps(state, setState, {
title: streamedTitle,
body: streamedBody,
});
```
Don't want to use Tambo's state management? You can use your own!
```tsx
const [state, setState] = useState({
title: "",
body: "",
});
useTamboStreamingProps(state, setState, {
title: streamedTitle,
body: streamedBody,
});
```
Works the same, but you don't get the benefits of Tambo's state management.
## When **not** to use `useTamboStreamingProps`
* The prop arrives **once** (e.g. static config fetched at build time).
* You need **custom reconciliation** that can't be expressed as a shallow merge.
* The incoming object is **huge** and diffing would dominate render time.
* You already debounce/queue updates **up-stream** (e.g. via a websocket buffer).
* You're on React **\< 18** and can't rely on concurrent rendering semantics.
## Glossary
* **dependency array** - the second argument to [`useEffect`](https://react.dev/reference/react/useEffect#dependencies) that tells React when the effect should re-run.
* **useEffect** - a React hook for performing side-effects after a component render. See the [official docs](https://react.dev/reference/react/useEffect) for details.
# Stream Status Provider
URL: /concepts/streaming/tambo-prop-stream-provider
The `TamboPropStreamProvider` uses a **compound component pattern** to manage streaming state. You wrap your content with the main provider and use its sub-components to define what renders at each streaming stage.
```tsx title="basic-usage.tsx"
import { TamboPropStreamProvider } from "@tambo-ai/react";
function WeatherCard({ location, temperature, condition }) {
return (
Loading weather...
{location}
{temperature}°C, {condition}
);
}
```
## Why Use the Stream Status Provider?
* **Declarative rendering** - Use compound components to define what shows in each state
* **Per-prop tracking** - Handle individual prop streaming (e.g., show title while body loads)
* **Enhanced UX** - Add highlighting, animations, or transitions during streaming
This guide builds on **[Streaming](/concepts/streaming)** and **[Component
Streaming Status](/concepts/streaming/component-streaming-status)**. We
recommend reading those first.
## API Reference
### Compound Components
**``** - Renders when the stream is pending (no data yet)
**``** - Renders when the stream is actively streaming data
**``** - Renders when data is successfully received and complete
### useTamboStream Hook
Access the stream context within the provider:
```tsx
const { data, streamStatus, getStatusForKey } = useTamboStream();
```
The **[useTamboStream](/concepts/streaming/use-tambo-stream)** hook provides
access to the stream context within the provider.
## Usage Examples
### Per-Prop Streaming
Track individual properties using the `streamKey` prop to show content progressively:
```tsx title="per-property-streaming.tsx"
function ArticleCard({ title, summary }) {
return (
Loading title...
{title}
Loading summary...
{summary}
);
}
```
### Error Handling and All States
Handle all possible streaming states including errors and empty states:
```tsx title="complete-error-handling.tsx"
function RobustComponent({ data }) {
const { streamStatus } = useTamboStreamStatus();
return (
AI is generating content...
No content generated yet
{data.content}
{streamStatus.isError && (
Error: {streamStatus.streamError?.message}
)}
);
}
```
### Real-Time Streaming with Fallbacks
Show streaming values immediately as they arrive with controlled fallbacks:
```tsx title="real-time-streaming.tsx"
function StreamingTextGenerator({ content, title, metadata }) {
return (
{title || "Generating title..."}
{title}
{content || "AI is writing..."}
{content}
Generated: {metadata.timestamp}
Words: {metadata.wordCount}
);
}
```
### Custom Animations
Add visual feedback during streaming:
```tsx title="custom-animations.tsx"
Loading title...
{title}
```
# Adding Tools
URL: /concepts/tools/adding-tools
Define your tool function and register it with tambo. Tools are asynchronous functions that take in a single argument and return a single value.
```tsx
//define the tool function. This is your own custom function and can perform any logic you want.
const getWeather = async (city: string) => {
try {
const weather = await fetch(
`http://api.weatherapi.com/v1/current.json?key=${process.env.NEXT_PUBLIC_WEATHER_API_KEY}&q=${city}`,
);
return weather.json();
} catch (error) {
throw new Error(`Failed to fetch weather for ${city}`);
}
};
// Create a TamboTool definition including your tool function
export const tools: TamboTool[] = [
{
name: "get_weather",
description: "Fetch current weather information for a specified city",
tool: getWeather,
toolSchema: z
.function()
.args(z.string().describe("The city to fetch weather for"))
.returns(
z.object({
location: z.object({
name: z.string(),
}),
}),
),
},
];
// Register your tools with Tambo
;
```
Now tambo can fetch weather information for a city when responding to a message!
## Returning Rich Content
By default, tool responses are converted to strings and sent back to the AI as text. However, tools can return rich content like images, audio, or mixed media by using the `transformToContent` parameter.
The `transformToContent` function transforms your tool's return value into an array of content parts before sending it back to the AI. This is useful when your tool needs to return images, audio files, or a combination of different content types.
```tsx
import { TamboTool } from "@tambo-ai/react";
import { z } from "zod";
const getProductImage = async (productId: string) => {
const product = await fetchProductData(productId);
return {
name: product.name,
description: product.description,
imageUrl: product.imageUrl,
price: product.price,
};
};
export const tools: TamboTool[] = [
{
name: "get_product_image",
description: "Fetch product information including image",
tool: getProductImage,
toolSchema: z
.function()
.args(z.string().describe("Product ID"))
.returns(
z.object({
name: z.string(),
description: z.string(),
imageUrl: z.string(),
price: z.number(),
}),
),
// Transform the result into content parts
transformToContent: (result) => [
{
type: "text",
text: `${result.name} - $${result.price}\n\n${result.description}`,
},
{
type: "image_url",
image_url: { url: result.imageUrl },
},
],
},
];
```
### Supported Content Types
The `transformToContent` function can return an array of content parts with the following types:
* **Text**: `{ type: "text", text: string }`
* **Image**: `{ type: "image_url", image_url: { url: string } }`
* **Audio**: `{ type: "input_audio", input_audio: { data: string, format: "wav" | "mp3" } }`
You can mix and match these content types to create rich, multimedia responses from your tools.
### When to Use transformToContent
Use `transformToContent` when your tool:
* Returns image URLs that should be displayed inline
* Generates audio that should be played
* Needs to return a combination of text and media
* Integrates with MCP servers (which already return content in this format)
If your tool only returns text or simple data, you don't need `transformToContent` - the default behavior will handle it automatically.
# Tools
URL: /concepts/tools
Tools are normal JavaScript functions that you give Tambo access to. When processing a user message, Tambo may decide to use tools you have registered to retrieve information or to take actions. Tools allow you to extend the capabilities of Tambo.
```tsx
const getWeather = (city: string) => {
return `The weather in ${city} is warm and sunny!`;
};
export const tools: TamboTool[] = [
{
name: "getWeather",
description: "A tool to get the current weather conditions of a city",
tool: getWeather,
toolSchema: z
.function()
.args(z.string().describe("The city name to get weather information for"))
.returns(z.string()),
},
];
;
```
# Auth0
URL: /concepts/user-authentication/auth0
Auth0 is a comprehensive identity and access management platform that provides secure authentication and authorization services. This guide shows how to integrate it with Tambo in a Next.js application.
This guide assumes you've already set up Auth0 in your Next.js application. If
you haven't, follow the [Auth0 Next.js Quick
Start](https://auth0.com/docs/quickstart/webapp/nextjs) first.
## Installation
Install the required packages:
```bash
npm install @auth0/nextjs-auth0 @tambo-ai/react
```
## Integration Options
### Server-Side Token Retrieval (Recommended)
Use this approach for better security and performance, especially when you don't need real-time authentication state changes.
```tsx title="app/layout.tsx"
import { getAccessToken } from "@auth0/nextjs-auth0";
import ClientLayout from "./client-layout";
export default async function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
let accessToken: string | undefined;
try {
// Get the access token from Auth0
const tokenResponse = await getAccessToken();
accessToken = tokenResponse.accessToken;
} catch (error) {
// User is not authenticated
console.log("User not authenticated");
}
return (
{children}
);
}
```
```tsx title="app/client-layout.tsx"
"use client";
import { UserProvider } from "@auth0/nextjs-auth0/client";
import { TamboProvider } from "@tambo-ai/react";
import { ReactNode } from "react";
interface ClientLayoutProps {
children: ReactNode;
userToken?: string;
}
export default function ClientLayout({
children,
userToken,
}: ClientLayoutProps) {
return (
{children}
);
}
```
### Client-Side Token Retrieval
Use this approach when you need real-time authentication state management or client-side routing with authentication guards.
First, create a token API endpoint:
```tsx title="app/api/auth/token/route.ts"
import { getAccessToken } from "@auth0/nextjs-auth0";
import { NextResponse } from "next/server";
export async function GET() {
try {
const { accessToken } = await getAccessToken();
return NextResponse.json({ accessToken });
} catch (error) {
return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
}
}
```
Then use Auth0's `useUser` hook in your client layout:
```tsx title="app/client-layout.tsx"
"use client";
import { UserProvider, useUser } from "@auth0/nextjs-auth0/client";
import { TamboProvider } from "@tambo-ai/react";
import { ReactNode, useEffect, useState } from "react";
interface ClientLayoutProps {
children: ReactNode;
}
function TamboWrapper({ children }: { children: ReactNode }) {
const { user, isLoading } = useUser();
const [accessToken, setAccessToken] = useState();
useEffect(() => {
if (user && !isLoading) {
const fetchToken = async () => {
try {
const response = await fetch("/api/auth/token");
const data = await response.json();
setAccessToken(data.accessToken);
} catch (error) {
console.error("Error fetching token:", error);
}
};
fetchToken();
}
}, [user, isLoading]);
return {children};
}
export default function ClientLayout({ children }: ClientLayoutProps) {
return (
{children}
);
}
```
## Usage
Once configured, you can use Tambo components throughout your application:
```tsx title="app/dashboard/page.tsx"
import { MessageThreadFull } from "@components/tambo/message-thread-full";
export default function Dashboard() {
return (
Dashboard
);
}
```
## Auth0 Configuration
Make sure your Auth0 application is configured with the appropriate scopes and settings:
### Required Scopes
Ensure your Auth0 application has the necessary scopes configured:
* `openid` - Required for OpenID Connect
* `profile` - Access to user profile information
* `email` - Access to user email address
### Token Configuration
In your Auth0 dashboard, verify that your application is configured to:
* Issue access tokens in JWT format
* Include the user's ID in the `sub` claim
* Have the appropriate audience configured if using APIs
Auth0 access tokens are JWTs that include the user's ID in the `sub` claim,
which is exactly what Tambo needs for user identification. The tokens are
automatically signed by Auth0 and can be verified using Auth0's public keys.
# Better Auth
URL: /concepts/user-authentication/better-auth
Better Auth is a modern authentication library that provides built-in support for multiple providers and plugins. This guide shows how to integrate it with Tambo in a Next.js application.
This guide assumes you've already set up Better Auth in your Next.js
application. If you haven't, follow the [Better Auth Next.js Quick
Start](https://www.better-auth.com/docs/installation) first.
## Installation
Install the required packages:
```bash
npm install better-auth @tambo-ai/react
```
## Integration Options
Choose the approach that best fits your application:
### Server-Side Token Retrieval (Recommended)
Use this approach when you want maximum security and don't need real-time authentication state changes in your UI.
**Benefits:**
* Tokens never appear in client-side JavaScript
* Better for SEO and initial page load performance
* No loading states for authentication
```tsx title="app/layout.tsx"
import { auth } from "./lib/auth"; // Your Better Auth instance
import ClientLayout from "./client-layout";
import { headers } from "next/headers";
export default async function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
const session = await auth.api.getSession({
headers: await headers(),
});
return (
{children}
);
}
```
```tsx title="app/client-layout.tsx"
"use client";
import { TamboProvider } from "@tambo-ai/react";
import { ReactNode } from "react";
interface ClientLayoutProps {
children: ReactNode;
userToken?: string;
}
export default function ClientLayout({
children,
userToken,
}: ClientLayoutProps) {
return {children};
}
```
### Client-Side Token Retrieval
Use this approach when you need real-time authentication state management or client-side routing with authentication guards.
**Benefits:**
* Real-time authentication state updates
* Better for single-page applications with client-side routing
* Allows for authentication state-dependent UI rendering
```tsx title="app/client-layout.tsx"
"use client";
import { authClient } from "./lib/auth-client";
import { TamboProvider } from "@tambo-ai/react";
import { ReactNode } from "react";
interface ClientLayoutProps {
children: ReactNode;
}
export default function ClientLayout({ children }: ClientLayoutProps) {
const { data: session } = authClient.useSession();
return {children};
}
```
## Usage
Once configured, you can use Tambo components throughout your application. The authentication context is automatically handled:
```tsx title="app/dashboard/page.tsx"
import { MessageThreadFull } from "@components/tambo/message-thread-full";
export default function Dashboard() {
return (
Dashboard
);
}
```
## Next Steps
Your Tambo integration is now complete. The `TamboProvider` will automatically:
* Exchange your Better Auth token for a Tambo token
* Refresh the Tambo token when it expires
* Handle authentication state changes
* Provide user isolation for all Tambo API calls
# Clerk
URL: /concepts/user-authentication/clerk
Clerk is a complete authentication and user management solution that handles authentication through middleware without requiring specific API routes. This guide shows how to integrate it with Tambo.
This guide assumes you've already set up Clerk in your Next.js application,
including middleware and sign-in/sign-up pages. If you haven't, follow the
[Clerk Next.js Quick Start](https://clerk.com/docs/quickstarts/nextjs) first.
## Installation
Install the required packages:
```bash
npm install @clerk/nextjs @tambo-ai/react
```
## Integration Options
### Server-Side Token Retrieval (Recommended)
Use this approach for better security and performance, especially when you don't need real-time authentication state changes.
```tsx title="app/layout.tsx"
import { auth } from "@clerk/nextjs/server";
import ClientLayout from "./client-layout";
export default async function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
const { getToken } = await auth();
const token = await getToken();
return (
{children}
);
}
```
```tsx title="app/client-layout.tsx"
"use client";
import { ClerkProvider } from "@clerk/nextjs";
import { TamboProvider } from "@tambo-ai/react";
import { ReactNode } from "react";
interface ClientLayoutProps {
children: ReactNode;
userToken?: string;
}
export default function ClientLayout({
children,
userToken,
}: ClientLayoutProps) {
return (
{children}
);
}
```
### Client-Side Token Retrieval
Use this approach when you need real-time authentication state management or client-side routing with authentication guards.
```tsx title="app/layout.tsx"
"use client";
import { ClerkProvider } from "@clerk/nextjs";
import ClientLayout from "./client-layout";
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
{children}
);
}
```
```tsx title="app/client-layout.tsx"
"use client";
import { useAuth } from "@clerk/nextjs";
import { TamboProvider } from "@tambo-ai/react";
import { ReactNode, useEffect, useState } from "react";
interface ClientLayoutProps {
children: ReactNode;
}
export default function ClientLayout({ children }: ClientLayoutProps) {
const { getToken, isLoaded, isSignedIn } = useAuth();
const [accessToken, setAccessToken] = useState();
useEffect(() => {
async function fetchToken() {
if (isLoaded && isSignedIn) {
try {
const token = await getToken();
setAccessToken(token || undefined);
} catch (error) {
console.error("Error fetching token:", error);
}
}
}
fetchToken();
}, [isLoaded, isSignedIn, getToken]);
return {children};
}
```
## Usage
Once configured, you can use Tambo components throughout your application:
```tsx title="app/dashboard/page.tsx"
import { MessageThreadFull } from "@components/tambo/message-thread-full";
export default function Dashboard() {
return (
Dashboard
);
}
```
## Advanced Configuration
### Custom JWT Templates
For advanced use cases, you can create custom JWT templates in Clerk to include specific claims:
1. Go to your Clerk Dashboard
2. Navigate to "JWT Templates"
3. Create a new template with the claims you need
4. Use the template name when calling `getToken()`:
```tsx
const token = await getToken({ template: "your-template-name" });
```
Clerk provides JWT tokens that include the user's ID in the `sub` claim, which
is exactly what Tambo needs for user identification. The token is
automatically signed and verified by Clerk.
# User Authentication
URL: /concepts/user-authentication
To ensure each of user in your application can see only their own threads and messages, Tambo allows you to bring your own authentication. Generate an auth token and pass it to Tambo, and configure how Tambo should verify the token to get a user ID. Preset configurations for many popular authentication providers are available to choose from.
```tsx
const userToken = useUserToken(); // Get token from your auth provider
...
;
```
# Neon
URL: /concepts/user-authentication/neon
Auth.js (formerly NextAuth.js) is a complete authentication solution that can use various database adapters. This guide shows how to integrate Tambo with Auth.js when using Neon as the database backend for session and user data storage.
This guide assumes you've already set up Auth.js with the Neon database
adapter. If you haven't, follow the [Neon Auth.js Integration
guide](https://neon.tech/docs/guides/auth-authjs) first.
## Installation
Install the required packages:
```bash
npm install next-auth @auth/neon-adapter @neondatabase/serverless @tambo-ai/react
```
## Auth.js Configuration
Configure Auth.js to use the Neon adapter and return access tokens:
```tsx title="app/api/auth/[...nextauth]/route.ts"
import NextAuth from "next-auth";
import { NeonAdapter } from "@auth/neon-adapter";
import { neon } from "@neondatabase/serverless";
import GoogleProvider from "next-auth/providers/google";
const sql = neon(process.env.NEON_DATABASE_URL!);
export const authOptions = {
adapter: NeonAdapter(sql),
providers: [
GoogleProvider({
clientId: process.env.GOOGLE_CLIENT_ID!,
clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
}),
],
callbacks: {
async jwt({ token, account }) {
if (account) {
token.accessToken = account.access_token;
}
return token;
},
async session({ session, token }) {
session.accessToken = token.accessToken as string;
return session;
},
},
};
const handler = NextAuth(authOptions);
export { handler as GET, handler as POST };
```
## Integration Options
### Server-Side Token Retrieval (Recommended)
Use this approach for better security and performance, especially when you don't need real-time authentication state changes.
```tsx title="app/layout.tsx"
import { getServerSession } from "next-auth/next";
import { authOptions } from "./api/auth/[...nextauth]/route";
import ClientLayout from "./client-layout";
export default async function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
const session = await getServerSession(authOptions);
return (
{children}
);
}
```
```tsx title="app/client-layout.tsx"
"use client";
import { TamboProvider } from "@tambo-ai/react";
import { ReactNode } from "react";
interface ClientLayoutProps {
children: ReactNode;
userToken?: string;
}
export default function ClientLayout({
children,
userToken,
}: ClientLayoutProps) {
return {children};
}
```
### Client-Side Token Retrieval
Use this approach when you need real-time authentication state management or client-side routing with authentication guards.
```tsx title="app/layout.tsx"
"use client";
import { SessionProvider } from "next-auth/react";
import ClientLayout from "./client-layout";
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
{children}
);
}
```
```tsx title="app/client-layout.tsx"
"use client";
import { useSession } from "next-auth/react";
import { TamboProvider } from "@tambo-ai/react";
import { ReactNode } from "react";
interface ClientLayoutProps {
children: ReactNode;
}
export default function ClientLayout({ children }: ClientLayoutProps) {
const { data: session } = useSession();
return (
{children}
);
}
```
## Usage
Once configured, you can use Tambo components throughout your application:
```tsx title="app/dashboard/page.tsx"
import { MessageThreadFull } from "@components/tambo/message-thread-full";
export default function Dashboard() {
return (
Dashboard
);
}
```
# Auth.js
URL: /concepts/user-authentication/nextauth
Auth.js (formerly NextAuth.js) is a complete authentication solution for Next.js applications. This guide demonstrates integration with Tambo using Google as the OAuth provider.
This guide assumes you've already set up Auth.js with Google OAuth in your
Next.js application. If you haven't, follow the [Auth.js Google Provider
documentation](https://authjs.dev/getting-started/providers/google) first.
## Installation
Install the required packages:
```bash
npm install next-auth @auth/core @tambo-ai/react
```
## Auth.js Configuration
First, configure Auth.js to return the access token in your API route:
```tsx title="app/api/auth/[...nextauth]/route.ts"
import NextAuth, { NextAuthOptions } from "next-auth";
import GoogleProvider from "next-auth/providers/google";
export const authOptions: NextAuthOptions = {
providers: [
GoogleProvider({
clientId: process.env.GOOGLE_CLIENT_ID!,
clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
}),
],
callbacks: {
async jwt({ token, account }) {
// Persist the OAuth access_token to the token right after signin
if (account) {
token.accessToken = account.access_token;
}
return token;
},
async session({ session, token }) {
// Send properties to the client
session.accessToken = token.accessToken as string;
return session;
},
},
};
const handler = NextAuth(authOptions);
export { handler as GET, handler as POST };
```
## TypeScript Configuration
Add the access token to your Auth.js session type:
```tsx title="types/next-auth.d.ts"
import "next-auth";
declare module "next-auth" {
interface Session {
accessToken?: string;
}
}
declare module "next-auth/jwt" {
interface JWT {
accessToken?: string;
}
}
```
## Integration Options
### Server-Side Token Retrieval (Recommended)
Use this approach for better security and performance, especially for server-rendered applications.
```tsx title="app/layout.tsx"
import { getServerSession } from "next-auth/next";
import { authOptions } from "./api/auth/[...nextauth]/route";
import ClientLayout from "./client-layout";
export default async function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
const session = await getServerSession(authOptions);
return (
{children}
);
}
```
```tsx title="app/client-layout.tsx"
"use client";
import { TamboProvider } from "@tambo-ai/react";
import { ReactNode } from "react";
interface ClientLayoutProps {
children: ReactNode;
userToken?: string;
}
export default function ClientLayout({
children,
userToken,
}: ClientLayoutProps) {
return {children};
}
```
### Client-Side Token Retrieval
Use this approach when you need real-time authentication state management or client-side routing.
```tsx title="app/layout.tsx"
"use client";
import { SessionProvider } from "next-auth/react";
import ClientLayout from "./client-layout";
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
{children}
);
}
```
```tsx title="app/client-layout.tsx"
"use client";
import { useSession } from "next-auth/react";
import { TamboProvider } from "@tambo-ai/react";
import { ReactNode } from "react";
interface ClientLayoutProps {
children: ReactNode;
}
export default function ClientLayout({ children }: ClientLayoutProps) {
const { data: session } = useSession();
return (
{children}
);
}
```
## Usage
Once configured, you can use Tambo components throughout your application:
```tsx title="app/dashboard/page.tsx"
import { MessageThreadFull } from "@components/tambo/message-thread-full";
export default function Dashboard() {
return (
Dashboard
);
}
```
## Important Considerations
Google access tokens expire after 1 hour. For production applications,
consider implementing token refresh logic or using Auth.js's built-in refresh
token capabilities.
Make sure your Google OAuth application has the necessary scopes configured.
The `openid`, `email`, and `profile` scopes are typically sufficient for user
identification.
# Overview
URL: /concepts/user-authentication/overview
In a Tambo application, each user has their own threads and messages, isolated from other users' data. This user isolation is achieved through secure token-based authentication.
## How Tambo Authentication Works
Tambo uses OAuth 2.0 [Token Exchange](https://datatracker.ietf.org/doc/html/rfc8693) to securely identify users. Here's what happens:
1. **Your app authenticates the user** with your chosen OAuth provider (Auth0, Clerk, etc.)
2. **Your app receives a JWT token** from the provider containing user information
3. **Your app exchanges this token with Tambo** via the `/oauth/token` endpoint
4. **Tambo returns a Tambo-specific token** that identifies the user for all subsequent API calls
## Token Requirements
Tambo supports any OAuth 2.0 provider that issues a [JSON Web Token (JWT)](https://datatracker.ietf.org/doc/html/rfc7519) with:
* A `sub` (subject) claim identifying the user
* Proper signature for verification (when JWT verification is enabled)
This includes most popular providers like Google, Microsoft, Auth0, Clerk, and others.
## Implementation Approaches
### Server-Side Token Retrieval (Recommended)
**Best for**: Most applications, especially those requiring server-side rendering or enhanced security.
* Tokens are retrieved on the server during page rendering
* More secure as tokens never appear in client-side JavaScript
* Better for SEO and initial page load performance
* Handles authentication state before the client renders
### Client-Side Token Retrieval
**Best for**: Highly interactive applications that need real-time authentication state changes.
* Tokens are retrieved in the browser after the page loads
* Allows for real-time authentication state management
* Required when using client-side routing with authentication guards
* May show loading states during token retrieval
## Using TamboProvider
The `TamboProvider` component from `@tambo-ai/react` handles the token exchange process automatically:
```tsx title="Basic Setup"
"use client";
// TamboProvider must be in a client component to manage authentication state
import { TamboProvider } from "@tambo-ai/react";
export default function Layout({ children }: { children: React.ReactNode }) {
const userToken = useUserToken(); // Get token from your auth provider
return {children};
}
```
TamboProvider needs to be in a client component because it manages
authentication state, handles token refresh, and provides React context to
child components. Server components cannot manage state or provide React
context.
## Provider-Specific Integration Guides
For detailed integration examples with popular authentication providers, see the following guides:
Learn how to integrate Tambo with Auth.js using Google OAuth as an example.
Step-by-step guide for integrating Tambo with Auth0 authentication.
Complete example of using Tambo with Clerk's authentication system.
Integration guide for Supabase Auth with Tambo in Next.js applications.
How to use Tambo with Auth.js and Neon PostgreSQL database integration.
Enterprise-grade authentication with WorkOS and Tambo integration.
Modern authentication toolkit with built-in support for multiple providers
and plugins.
## JWT Verification Strategies
When your OAuth provider supports OpenID Connect Discovery (most do), Tambo automatically verifies tokens. For providers that don't, you can configure verification in your project dashboard:
* **OpenID Connect Discovery** (Default): Automatic verification using the provider's public keys
* **Asymmetric JWT Verification**: Manual verification using a provided public key
* **Symmetric JWT Verification**: Verification using a shared secret (testing only)
* **None**: No verification (development only)
Supabase Auth doesn't support asymmetric JWT verification. You'll need to
disable JWT verification in your Tambo project settings when using Supabase.
All verification strategies can be configured in your project dashboard under Settings > User Authentication.
# Supabase
URL: /concepts/user-authentication/supabase
Supabase Auth is a complete authentication solution that integrates seamlessly with your Supabase database. This guide shows how to integrate it with Tambo in a Next.js application.
This guide assumes you've already set up Supabase Auth in your Next.js
application, including the auth callback route. If you haven't, follow the
[Supabase Next.js Quick
Start](https://supabase.com/docs/guides/auth/quickstarts/nextjs) first.
Supabase Auth doesn't support asymmetric JWT verification. You **must**
disable JWT verification in your Tambo project settings (Settings > User
Authentication > Verification Strategy > None) when using Supabase Auth.
## Installation
Install the required packages:
```bash
npm install @supabase/supabase-js @tambo-ai/react
```
## Integration Options
### Server-Side Token Retrieval (Recommended)
Use this approach for better security and performance, especially when you don't need real-time authentication state changes.
```tsx title="app/layout.tsx"
import { createServerClient } from "@supabase/supabase-js";
import { cookies } from "next/headers";
import ClientLayout from "./client-layout";
export default async function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
const supabase = createServerClient(
process.env.NEXT_PUBLIC_SUPABASE_URL!,
process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
{
cookies: {
get(name: string) {
return cookies().get(name)?.value;
},
},
},
);
const {
data: { session },
} = await supabase.auth.getSession();
return (
{children}
);
}
```
```tsx title="app/client-layout.tsx"
"use client";
import { TamboProvider } from "@tambo-ai/react";
import { ReactNode } from "react";
interface ClientLayoutProps {
children: ReactNode;
userToken?: string;
}
export default function ClientLayout({
children,
userToken,
}: ClientLayoutProps) {
return {children};
}
```
### Client-Side Token Retrieval
Use this approach when you need real-time authentication state management or client-side routing with authentication guards.
```tsx title="app/client-layout.tsx"
"use client";
import { TamboProvider } from "@tambo-ai/react";
import { createClient } from "@/lib/supabase";
import { ReactNode, useEffect, useState } from "react";
interface ClientLayoutProps {
children: ReactNode;
}
export default function ClientLayout({ children }: ClientLayoutProps) {
const [accessToken, setAccessToken] = useState();
const supabase = createClient();
useEffect(() => {
// Get initial session
const getInitialSession = async () => {
const {
data: { session },
} = await supabase.auth.getSession();
setAccessToken(session?.access_token);
};
getInitialSession();
// Listen for auth changes
const {
data: { subscription },
} = supabase.auth.onAuthStateChange((_event, session) => {
setAccessToken(session?.access_token);
});
return () => subscription.unsubscribe();
}, [supabase]);
return {children};
}
```
## Usage
Once configured, you can use Tambo components throughout your application:
```tsx title="app/dashboard/page.tsx"
import { MessageThreadFull } from "@components/tambo/message-thread-full";
export default function Dashboard() {
return (
Dashboard
);
}
```
## Supabase-Specific Features
### Automatic Token Refresh
Supabase automatically handles token refresh in the background. When tokens expire, Supabase will automatically refresh them, and the TamboProvider will receive the updated token through the auth state change listener.
### Session Management
Supabase provides robust session management across tabs and devices. The auth state change listener ensures that authentication state stays synchronized across your application.
Supabase uses symmetric JWT signing (HMAC-SHA256) rather than asymmetric
signing (RS256). Tambo's JWT verification is designed for asymmetric tokens
from OAuth providers. Since Supabase handles authentication security,
disabling JWT verification in Tambo is safe and recommended.
# WorkOS
URL: /concepts/user-authentication/workos
WorkOS is an enterprise-grade authentication and user management platform that provides features like SSO, SCIM provisioning, and directory sync. This guide shows how to integrate it with Tambo in a Next.js application.
This guide assumes you've already set up WorkOS in your Next.js application,
including the callback route for handling authentication responses. If you
haven't, follow the [WorkOS Next.js Quick
Start](https://workos.com/docs/user-management/nextjs) first.
## Installation
Install the required packages:
```bash
npm install @workos-inc/node @tambo-ai/react
```
## Integration Options
### Server-Side Token Retrieval (Recommended)
Use this approach for better security and performance, especially when you don't need real-time authentication state changes.
```tsx title="app/layout.tsx"
import { getSession } from "@workos-inc/node/middleware";
import ClientLayout from "./client-layout";
export default async function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
const session = await getSession({
cookiePassword: process.env.WORKOS_COOKIE_PASSWORD!,
});
return (
{children}
);
}
```
```tsx title="app/client-layout.tsx"
"use client";
import { TamboProvider } from "@tambo-ai/react";
import { ReactNode } from "react";
interface ClientLayoutProps {
children: ReactNode;
userToken?: string;
}
export default function ClientLayout({
children,
userToken,
}: ClientLayoutProps) {
return {children};
}
```
### Client-Side Token Retrieval
Use this approach when you need real-time authentication state management or client-side routing with authentication guards.
First, create a custom hook for WorkOS authentication:
```tsx title="hooks/use-workos-auth.ts"
import { useEffect, useState } from "react";
interface UseWorkOSAuthReturn {
accessToken: string | null;
user: any | null;
loading: boolean;
}
export function useWorkOSAuth(): UseWorkOSAuthReturn {
const [accessToken, setAccessToken] = useState(null);
const [user, setUser] = useState(null);
const [loading, setLoading] = useState(true);
useEffect(() => {
const fetchSession = async () => {
try {
const response = await fetch("/api/auth/session");
if (response.ok) {
const data = await response.json();
setAccessToken(data.accessToken);
setUser(data.user);
}
} catch (error) {
console.error("Error fetching session:", error);
} finally {
setLoading(false);
}
};
fetchSession();
}, []);
return { accessToken, user, loading };
}
```
Create a session API endpoint:
```tsx title="app/api/auth/session/route.ts"
import { NextRequest, NextResponse } from "next/server";
import { getSession } from "@workos-inc/node/middleware";
export async function GET(request: NextRequest) {
try {
const session = await getSession({
cookiePassword: process.env.WORKOS_COOKIE_PASSWORD!,
});
if (!session?.accessToken) {
return NextResponse.json({ error: "No access token" }, { status: 401 });
}
return NextResponse.json({
accessToken: session.accessToken,
user: session.user,
});
} catch (error) {
return NextResponse.json({ error: "Invalid session" }, { status: 401 });
}
}
```
Use the hook in your client layout:
```tsx title="app/client-layout.tsx"
"use client";
import { TamboProvider } from "@tambo-ai/react";
import { useWorkOSAuth } from "@/hooks/use-workos-auth";
import { ReactNode } from "react";
interface ClientLayoutProps {
children: ReactNode;
}
export default function ClientLayout({ children }: ClientLayoutProps) {
const { accessToken, loading } = useWorkOSAuth();
if (loading) {
return Loading...
;
}
return (
{children}
);
}
```
## Usage
Once configured, you can use Tambo components throughout your application:
```tsx title="app/dashboard/page.tsx"
import { MessageThreadFull } from "@components/tambo/message-thread-full";
export default function Dashboard() {
return (
Dashboard
);
}
```
## WorkOS Enterprise Features
WorkOS provides several enterprise-grade features that work seamlessly with Tambo:
### Single Sign-On (SSO)
* **SAML 2.0 & OpenID Connect**: Support for enterprise identity providers
* **Directory Sync**: Automatic user provisioning and deprovisioning
* **Domain Verification**: Restrict access to verified domains
### User Management
* **SCIM Provisioning**: Automated user lifecycle management
* **Multi-factor Authentication**: Built-in MFA support
* **Audit Logs**: Complete authentication and authorization tracking
WorkOS access tokens include enterprise-specific claims and are designed for
high-security environments. The token automatically includes the necessary
user identification and organizational context that Tambo needs.
# Component State
URL: /concepts/components/component-state
Components generated by Tambo may have internal state values that are updated by user interactions after the component is rendered. To allow Tambo to track the current value of a component's internal state, replace `useState` with `useTamboComponentState`.
This allows Tambo to consider the current state values when responding to subsequent user messages, and allows rendering previous thread messages with their latest values.
import { ImageZoom } from "fumadocs-ui/components/image-zoom";
## Tracking State with `useTamboComponentState`
Consider this simple React component that allows a user to update an `emailBody` field, and tracks whether the email has been sent:
```tsx title="Simple email component"
export const EmailSender = () => {
...
const [emailBody, setEmailBody] = useState("") // tracks the message being typed
const [isSent, setIsSent] = useState(false) // tracks whether the 'send' button has been clicked
...
}
```
If Tambo renders this component and the user edits the `emailBody` field, Tambo will not know about the edit. A following user message like "Help me edit what I've typed so far" will not generate a relevant response.
To allow Tambo to see these state values, simply replace `useState` with `useTamboComponentState`, and pass a `keyName` for each value:
```tsx title="Email component with tambo state"
import { useTamboComponentState } from "@tambo-ai/react";
export const EmailSender = () => {
...
const [emailBody, setEmailBody] = useTamboComponentState("emailBody", "");
const [isSent, setIsSent] = useTamboComponentState("isSent", false);
...
}
```
Now tambo will know the current values of `emailBody` and `isSent`.
## Updating editable state from props
Often when we have an editable state value, like the `emailBody` above, we want Tambo to be able to generate and stream in the initial value. If a user sends "Help me generate an email asking about a good time to meet," Tambo should be able to fill in the value with relevant text, and then the user should be able to edit it.
When using `useState` this can be done by adding a `useEffect` that updates the state value with prop value changes:
```tsx title="Simple email component"
export const EmailSender = ({ initialEmailBody }: { initialEmailBody: string }) => {
...
const [emailBody, setEmailBody] = useState("") // tracks the message being typed
const [isSent, setIsSent] = useState(false) // tracks whether the 'send' button has been clicked
useEffect(() => {
setEmailBody(initialEmailBody)
}, [initialEmailBody])
...
}
```
However, when using `useTamboComponentState`, this pattern will cause the initial prop value to overwrite the latest stored state value when re-rendering a previously generated component.
Instead, use the `setFromProp` parameter of `useTamboComponentState` to specify a prop value that should be used to set the initial state value:
```tsx title="Simple email component"
export const EmailSender = ({ initialEmailBody }: { initialEmailBody: string }) => {
...
const [emailBody, setEmailBody] = useTamboComponentState("emailBody", "", initialEmailBody) // tracks the message being typed, and sets initial value from the prop
const [isSent, setIsSent] = useTamboComponentState("isSent", false) // tracks whether the 'send' button has been clicked
...
}
```
# Defining Tambo Components
URL: /concepts/components/defining-tambo-components
Tell Tambo which components it can use in responses, what they are for, and what props they expect by defining a `TamboComponent` for each.
```tsx
import { z } from "zod";
import { DataChart } from "@/components/DataChart";
import { TamboProvider } from "@tambo-ai/react";
// Define the schema with Zod
export const DataChartProps = z.object({
data: z.object({
labels: z.array(z.string()),
values: z.array(z.number()),
}),
type: z.enum(["bar", "line", "pie"]),
});
const tamboComponents: TamboComponent[] = [
{
component: DataChart,
name: "DataChart",
description: "Displays data as a chart",
propsSchema: DataChartProps,
},
];
;
```
Note that when using zod's `.optional()` on a field, tambo may not attempt to generate any value for the prop.
You can also use `z.describe()` to provide extra guidance to the AI:
```tsx
import { z } from "zod";
import { DataChart } from "@/components/DataChart";
import { TamboProvider } from "@tambo-ai/react";
// Define schema with descriptions for AI
export const DataChartProps = z
.object({
data: z
.object({
labels: z
.array(z.string())
.describe("Use single words or short phrases."),
values: z.array(z.number()).describe("Use whole numbers."),
})
.describe("A component for displaying data in various chart formats"),
type: z
.enum(["bar", "line", "pie"])
.describe(
"Use a chart type that is appropriate for the data. Only use pie charts when less than 5 values.",
),
})
.describe("A component for displaying data in various chart formats");
const tamboComponents: TamboComponent[] = [
{
component: DataChart,
name: "DataChart",
description: "Displays data as a chart",
propsSchema: DataChartProps,
},
];
;
```
This registration approach is for components that Tambo generates from scratch. If you want to pre-place components on your page and let Tambo modify them, use [Interactable Components](./interactable-components) instead—they register themselves automatically when mounted.
If you want Tambo to both modify pre-placed interactable components AND be able to generate new instances inline, register the component in the `TamboProvider` components array as well.
Now when a user sends a message asking about something related to your components, Tambo can respond with the appropriate component filled with relevant data!
# Registering Components
URL: /concepts/components
Register your React components as UI tools that Tambo can intelligently choose and populate with data. Tell Tambo which components are available and what props they expect. This enables conversational control of your app where users can ask for specific functionality and Tambo responds with the appropriate component filled with relevant data.
```tsx
const components: TamboComponent[] = [
{
name: "WeatherDisplay",
description: "A display of the weather in a city",
component: WeatherDisplayComponent,
propsSchema: WeatherDisplayPropsSchema,
},
{
name: "UserProfile",
description: "A user profile card with avatar and basic information",
component: UserProfileComponent,
propsSchema: UserProfilePropsSchema,
},
];
;
```
# Interactable Components
URL: /concepts/components/interactable-components
When you want to place specific components on screen rather than letting Tambo choose which to show, but still want to allow your users to interact with them using natural language, use Tambo's Interactable components.
Unlike regular registered components that Tambo generates and renders from scratch when responding to messages, interactable components are pre-placed by you while still allowing Tambo to modify their props.
## Creating Interactable Components
The easiest way to make a component interactable to Tambo is by using `withInteractable`. Pass in your component, a name, a description, and the props schema, and get an interactable version of your component that Tambo knows about.
1. **Build the presentational component.** Use `useEffect` to keep any local UI state aligned with incoming props from Tambo.
```tsx
import { useEffect, useState } from "react";
type NoteProps = {
title: string;
content: string;
color?: "white" | "yellow" | "blue" | "green";
};
export function Note({ title, content, color = "yellow" }: NoteProps) {
const [draftContent, setDraftContent] = useState(content);
useEffect(() => {
setDraftContent(content);
}, [content]);
return (
[Github](https://github.com/tambo-ai/tambo-template?tab=readme-ov-file#tambo-template)
```bash title="Install the starter app:"
npm create tambo-app@latest my-tambo-app
```
This template app shows how to setup the fundamental parts of an AI application using tambo:
**Component registration**
See in [src/lib/tambo.ts](https://github.com/tambo-ai/tambo-template/blob/main/src/lib/tambo.ts) how a graph component is registered with tambo.
**Tool Registration**
See in [src/lib/tambo.ts](https://github.com/tambo-ai/tambo-template/blob/main/src/lib/tambo.ts) how population data tools are registered with tambo.
**UI for sending messages to tambo and showing responses**
The components used within [src/components/tambo/message-thread-full.tsx](https://github.com/tambo-ai/tambo-template/blob/main/src/components/tambo/message-thread-full.tsx) use hooks from tambo's react SDK to send messages and show the thread history.
**Wrap the app with the `TamboProvider`**
In [src/app/chat/page.tsx](https://github.com/tambo-ai/tambo-template/blob/main/src/app/chat/page.tsx) we wrap the page with the `TamboProvider` to enable the usage of tambo's react SDK within the message sending and thread UI components.
# Supabase MCP Client App
URL: /examples-and-templates/supabase-mcp-client
Add MCP server tools and UI tools to a React app using tambo to build an AI app with minimal custom code.
Use this as a starting point to build apps to interact with any MCP server.
[Github](https://github.com/tambo-ai/supabase-mcp-client/tree/main?tab=readme-ov-file#supabase-mcp-client-react-app)
This application makes use of tambo's `TamboMcpProvider` to easily add the tools defined by the official [Supabase MCP server](https://github.com/supabase-community/supabase-mcp).
Custom react components to show interactive visualizations of the responses from the Supabase tools are registered with tambo in [src/lib/tambo.ts](https://github.com/tambo-ai/supabase-mcp-client/blob/main/src/lib/tambo.ts)
# Suggestions
URL: /concepts/suggestions
Tambo automatically analyzes user interactions and generates contextual suggestions after each assistant message. You can also override these with custom suggestions using the `useTamboContextAttachment` hook.
## Using Suggestions
### The useTamboSuggestions Hook
The main way to interact with suggestions is through the `useTamboSuggestions` hook:
```tsx title="thread-with-suggestions.tsx"
import { useTamboSuggestions } from "@tambo-ai/react";
function ThreadWithSuggestions() {
const {
suggestions, // Array of current suggestions
isLoading, // Whether suggestions are being generated or loading
isAccepting, // Whether a suggestion is being applied
error, // Current error message, if any
accept, // Function to apply a suggestion
} = useTamboSuggestions({
maxSuggestions: 3, // Optional: Number of suggestions to generate (1-10)
});
if (isLoading) return 
))}