Overview
useTamboThreadList is a React Query hook for fetching a paginated list of threads with automatic caching and refetching.
Import
import { useTamboThreadList } from '@tambo-ai/react';
Signature
function useTamboThreadList(
listOptions?: ThreadListParams,
queryOptions?: UseQueryOptions<ThreadListResponse>
): UseQueryResult<ThreadListResponse>
Parameters
Filtering and pagination options
User identifier to filter threads (optional if provided via TamboProvider context)
Maximum number of threads to return (default: 20)
Pagination cursor from previous response
Sort order by creation date (default: ‘desc’)
queryOptions
UseQueryOptions<ThreadListResponse>
Additional React Query options
Whether the query should automatically run
Interval in milliseconds to automatically refetch
Return Value
The thread list response
Whether more threads are available
Cursor for fetching the next page
Whether the initial data is being loaded
Whether an error occurred
Error object if the query failed
Function to manually refetch the list
Behavior
- Stale Time: Thread list is considered stale after 5 seconds
- User Context: Automatically uses
userKey from TamboProvider if not explicitly provided
- Authentication: Automatically disabled until user is identified
- Pagination: Supports cursor-based pagination for efficient loading
Examples
Basic Usage
import { useTamboThreadList } from '@tambo-ai/react';
function ThreadList() {
const { data, isLoading, isError } = useTamboThreadList({
limit: 20,
});
if (isLoading) {
return <div>Loading threads...</div>;
}
if (isError) {
return <div>Error loading threads</div>;
}
return (
<ul>
{data.threads.map(thread => (
<li key={thread.id}>
<h3>{thread.name || 'Untitled'}</h3>
<p>Status: {thread.runStatus}</p>
<time>{new Date(thread.createdAt).toLocaleDateString()}</time>
</li>
))}
</ul>
);
}
import { useState } from 'react';
import { useTamboThreadList } from '@tambo-ai/react';
function PaginatedThreadList() {
const [cursor, setCursor] = useState<string | undefined>();
const { data, isLoading } = useTamboThreadList({
limit: 10,
cursor,
});
if (isLoading) return <Spinner />;
return (
<div>
<ul>
{data.threads.map(thread => (
<ThreadItem key={thread.id} thread={thread} />
))}
</ul>
{data.hasMore && (
<button onClick={() => setCursor(data.nextCursor!)}>
Load More
</button>
)}
</div>
);
}
For Specific User
Override the context userKey:
function UserThreadList({ userId }: { userId: string }) {
const { data, isLoading } = useTamboThreadList({
userKey: userId, // Explicit userKey
limit: 50,
});
if (isLoading) return <Spinner />;
return (
<div>
<h2>Threads for {userId}</h2>
<ThreadGrid threads={data.threads} />
</div>
);
}
With Sorting
function SortedThreadList() {
const [order, setOrder] = useState<'asc' | 'desc'>('desc');
const { data, isLoading } = useTamboThreadList({
order,
limit: 20,
});
return (
<div>
<select value={order} onChange={e => setOrder(e.target.value as 'asc' | 'desc')}>
<option value="desc">Newest First</option>
<option value="asc">Oldest First</option>
</select>
{isLoading ? (
<Spinner />
) : (
<ThreadList threads={data.threads} />
)}
</div>
);
}
function ThreadSidebar() {
const [selectedId, setSelectedId] = useState<string>();
const { data, isLoading } = useTamboThreadList({ limit: 100 });
if (isLoading) return <SidebarSkeleton />;
return (
<aside>
<h2>Conversations</h2>
<ul>
{data.threads.map(thread => (
<li
key={thread.id}
className={selectedId === thread.id ? 'selected' : ''}
onClick={() => setSelectedId(thread.id)}
>
<span>{thread.name || 'New conversation'}</span>
<time>{formatRelativeTime(thread.updatedAt)}</time>
</li>
))}
</ul>
</aside>
);
}
useTamboThread
Fetch a single thread
useTambo
Main hook for thread state
Thread Types
Thread type definitions
Threads Concept
Learn about threads