useThreads
React hook for listing, managing, and syncing conversation threads with useThreads. Rename, archive, delete, and paginate threads with realtime updates via WebSocket.
Overview
useThreads is a React hook for managing conversation threads in CopilotKit Intelligence. It fetches the thread list for a given agent, keeps it synchronized in realtime via WebSocket, and exposes mutation methods for renaming, archiving, and deleting threads. For a full walkthrough, see Headless Threads.
Thread persistence runs in CopilotKit Intelligence, which is
accessed with a publicLicenseKey. That key is not yet supported on React
Native (see CopilotKitProvider),
so useThreads is documented here for API parity but is not yet usable on
React Native.
Re-exported from @copilotkit/react-core/v2, identical to the React (V2) useThreads. The only difference is the import path.
Threads are sorted by most recent run first. The hook supports cursor-based pagination when a limit is provided.
Signature
import { useThreads } from "@copilotkit/react-native";
function useThreads(input: UseThreadsInput): UseThreadsResultParameters
Prop
Type
Return Value
Prop
Type
Usage
import { useThreads } from "@copilotkit/react-native";
import { FlatList, Text, TouchableOpacity, View } from "react-native";
function ThreadList() {
const {
threads,
isLoading,
renameThread,
archiveThread,
deleteThread,
} = useThreads({ agentId: "my-agent" });
if (isLoading) {
return (
<View>
<Text>Loading threads...</Text>
</View>
);
}
return (
<FlatList
data={threads}
keyExtractor={(thread) => thread.id}
renderItem={({ item: thread }) => (
<View>
<Text>{thread.name ?? "Untitled"}</Text>
<TouchableOpacity onPress={() => renameThread(thread.id, "New name")}>
<Text>Rename</Text>
</TouchableOpacity>
<TouchableOpacity onPress={() => archiveThread(thread.id)}>
<Text>Archive</Text>
</TouchableOpacity>
<TouchableOpacity onPress={() => deleteThread(thread.id)}>
<Text>Delete</Text>
</TouchableOpacity>
</View>
)}
/>
);
}Behavior
- On mount, fetches the thread list and establishes a realtime WebSocket subscription. AG-UI Streams & Framework Threads explains the event replay model and the WebSocket sync.
- Thread creates, renames, archives, and deletes from any client are reflected immediately without polling.
- Mutations update the list at once, before the server confirms. If the server rejects a delete, the thread comes back and
erroris set. Rename, archive, and unarchive do not roll back. Promises resolve when the server accepts the request and reject on failure. - The
errorstate updates with the most recent error from any operation. - The
threadsarray is sorted by most recent run first (lastRunAt, thenupdatedAt, thencreatedAt). For a thread that has run, a rename or archive does not change its place. - New threads are automatically named when their first run creates them. By default, the name is the first user message. To get a short summary title from a model, set
generateThreadNames: { model }on the runtime.
How is this guide?